Internet Security and Acceleration Server 2000

Internet Security and Acceleration Server 2000 Start Page

Microsoft Internet Security and Acceleration (ISA) Server 2000

Version 3.0

Purpose

Microsoft® Internet Security and Acceleration (ISA) Server 2000 is an extensible platform that integrates firewall and cache features, and routes requests and responses between the Internet and client computers. ISA provides filtering to block access to specific sites, and uses network address translation (NAT) and other methods to enable secure access between an intranet and the Internet. This documentation includes information and libraries for developing firewall extensions, administration tools, security applications, and other components that integrate with and build on the ISA platform.

Where Applicable

ISA services include firewall services, advanced caching capabilities, packet filtering, and alerting. This documentation includes information relevant to developers wanting to extend these features.

Audience

The information in this documentation for ISA Server is relevant to programmers, system administrators, and tool vendors. To use this documentation programming experience in the following areas is desirable:

•Visual C++® or Visual Basic® applications

•Visual Basic Scripting Edition (VBScript) or JScript®

Run-Time Requirements

To run ISA Server requires Windows 2000 Server.

Overview

General information about ISA Server.

Implementation

How to use ISA Server.

Reference

Documentation of ISA Server administration COM objects, interfaces, structures, and enumerated types.

Feedback

Make error reports and feature requests directly to Microsoft.

Built on Tuesday, May 23, 2000


Legal Information

Microsoft Internet Security and Acceleration (ISA) Server 2000

This documentation is an early release of the final documentation, which may be changed substantially prior to final commercial release, and is confidential and proprietary information of Microsoft Corporation. It is disclosed pursuant to a non-disclosure agreement between the recipient and Microsoft. This document is provided for informational purposes only and Microsoft makes no warranties, either express or implied, in this document. Information in this document, including URL and other Internet Web site references, is subject to change without notice. The entire risk of the use or the results of the use of this document remains with the user. Unless otherwise noted, the example companies, organizations, products, people and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unpublished work. © 1999-2000 Microsoft Corporation. All rights reserved.

Microsoft, Windows, Windows NT, Active Directory, DirectX, JScript, MSDN, NetShow, Visual Basic, Visual C++, and Win32 are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Macintosh is a trademark of Apple Computer, Inc., used under license.

Intrusion detection functionality based on technology from Internet Security Systems, Inc., Atlanta, Ga., USA, www.iss.net. and Portions Copyright © 1999 Internet Security Systems, Inc.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.


About Internet Security and Acceleration

[This is preliminary documentation and subject to change.]

The Microsoft® Internet Security and Acceleration (ISA) Server 2000 integrates firewall and cache features to secure networks and improve their performance. ISA Server is an extensible platform that provides security, hardware redundancy and load balancing, efficient use of network resources by means of sophisticated caching mechanisms, and administration tools. ISA services consist of several technologies:

  • The Firewall service.
  • The w3proxy Web proxy service.
  • Secure network address translation (SecureNAT).
  • Advanced caching capabilities, including RAM caching and use of the Cache Array Routing Protocol (CARP).
  • Bandwidth control.
  • Static and dynamic Internet Protocol (IP) packet filtering.
  • Alerting.

For more information see the ISA product documentation.

This section contains the following topics:

  • ISA Architecture
  • About ISA Administration
  • About the ISA Firewall
  • About the ISA Cache


ISA Architecture

This section provides basic information regarding the architecture of Internet Security and Acceleration (ISA). This information is useful to developers who require a broad view of ISA before developing extensions and filters using the ISA Software Developer's Kit (SDK).

This section includes the diagrams for network and server viewing.


Network View

The following figure shows the architecture of ISA on the network scale.

ISA Server is typically configured on a device with two network interfaces. One network interface connects directly to the private network, while the other interface connects to the public Internet. The interfaces can be any type that permits protocol bindings. On a local area network (LAN), for example, Ethernet, token ring network, or Attached Resource Computer Network (ARCnet) is commonly bound to Transmission Control Protocol/Internet Protocol (TCP/IP) or NetBIOS Enhanced User Interface (NetBEUI). An Internet connection might utilize a modem, Integrated Services Digital Network (ISDN), or network interface that connects to a router that connects to the Internet.

At the center of ISA is the administrator's computer. The administrator's computer links the functionality of the ISA Server, the Active Directory™ in Microsoft® Windows® 2000, and the ISA Component Object Model (COM) object. The administrator can also manage clients from a remote location, using either the ISA Server administration tool or scripting. For information on the administration tool, see the ISA product documentation. For more information on scripting, see ISA Administration Scripting.

The administrator's tasks include establishing ISA Server rules and policies. ISA Server rules determine how ISA Server clients communicate with the Internet and the type of communication that is allowed. These rules also determine how servers on your local network communicate with Internet users. A policy consists of site and content rules, protocol rules, Web publishing rules, and IP packet filters.

A policy can be applied at the domain-array level or the enterprise level. The enterprise consists of all the domain arrays in the network. Enterprise policies can be applied to all or some of the domain arrays in the enterprise, either exclusively or in addition to the domain-array policy. For more information, see the ISA product documentation.

Four items are shown in the network view figure:

  • The remote computer from which an administrator administers ISA.
  • The ISA Server domain array, consisting of at least one computer. The functionality of the ISA Server domain array is shown in detail in the Network View figure.
  • Active Directory, located on a separate computer. Active Directory stores information about all the objects on a network, including users, and computers, and stores enterprise and domain-array policy and registration information related to ISA and its extensions. Active Directory distributes that information throughout the network. The registry on the ISA computer can perform these functions where a directory service is not in use.

    For more information see Directory Service in the Windows 2000 documentation.

  • The clients and servers that use the ISA Server firewall and cache capabilities.

You can programmatically perform any ISA administration tasks by accessing ISA's COM objects through the ISA COM root object. You can use scripting to automate administrative tasks, including those related to ISA client machines. For more information, see ISA Administration Scripting.


Server View

The figure below shows in detail the architecture of the ISA Server domain array.

An ISA Server may be included in a domain array, to allow for load balancing and fault tolerance. This is described further in the ISA product documentation. The following explanation focuses on a single ISA server's architecture. The server includes these components:

  • IP packet filter. As shown, the ISA server as a whole relies on the function of the IP packet filter. For more information, see the section on IP packet filtering in the ISA Server product documentation.
  • SecureNAT is a function of ISA server that performs network address translation (NAT) in place of the Windows 2000 NAT function. For more information about SecureNAT, see the ISA Server product documentation.
  • The firewall, consisting of the Web proxy service, Firewall service, and application filters:
    • The Web proxy service, which includes Web (ISAPI) filters and the cache.
    • The Firewall service, which handles connect requests by Firewall service and SecureNAT clients. HTTP requests are diverted to the Web proxy service by the HTTP filter.
    • Application filters. These include the HTTP filter, which redirects HTTP requests to the Web proxy service, and other protocol filters provided with ISA. Third-party filters can be developed for the ISA firewall by using the application filter interfaces.

ISA also makes use of the bandwidth control functionality of Quality of Service (QOS) in Windows 2000. QOS is a collection of components that manages bandwidth use for a network. ISA applies QOS to connections according to rules established by the ISA administrator.

As illustrated in the preceding diagram, ISA Server protects three types of clients:

  • ISA Firewall clients are computers that have ISA Firewall client software installed. Requests from ISA Firewall clients are directed to the ISA Firewall service on the ISA Server computer, to determine whether access is allowed. Subsequently, the can be filtered by application filters and other add-ins. If the ISA Firewall client requests an HTTP object, the HTTP filter redirects the request to the Web proxy service. The Web proxy service may also cache the requested object, or serve the object from the ISA Server cache. For more information on Firewall clients, see Firewall Client.
  • SecureNAT clients are computers that do not have ISA Firewall client software installed. Requests from SecureNAT clients are directed first to the NAT driver, which substitutes a global IP address that is valid on the Internet for the internal IP address of the S-NAT client. The client request is then directed to the ISA Firewall service, to determine whether access is allowed. Finally, the request can be filtered by application filters and other add-ins. If the SecureNAT client requests an HTTP object, the HTTP filter redirects the request to the Web proxy service. The Web proxy service may also cache the requested object, or serve the object from the ISA Server cache.
  • Web proxy clients are any browser application compatible with the standards of Conseil Europeen pour la Recherche Nucleaire (CERN). ISA redirects requests from Web proxy clients to the Web proxy service on the ISA Server computer to determine whether access is allowed. The Web proxy service can also cache the requested object or serve the object from the ISA Server cache.


About ISA Administration

The Internet Security and Acceleration (ISA) administration COM object model allows you to extend ISA functionality. The administration objects also allow for automation of everything that is done through the administration tool. This means that any task can be automated by an ISA administrator by using the administration objects.

See ISA Administration Scripting for examples of using the objects to automate administrative tasks.

This section contains the following topics:

  • ISA Administration Object Model
  • About Administration Scripting


ISA Administration Object Model

The following diagram displays the administration COM objects hierarchy. The diagram shows the top of the hierarchy, starting with the root object. Gray boxes represent collections and white boxes represent objects. Click boxes at the bottom of the diagram to continue down through the entire hierarchy.

FPCArray Object Model

FPCEnterprisePolicies Object Model

FPCArrayPolicy Object Model

The following section shows the administration objects derived from the FPCArray object. Gray boxes represent collections and white boxes represent objects. Click boxes at the bottom of the diagram to continue down through the entire hierarchy.

FPCPolicyElements Object Model

The following diagram shows the administration objects that are derived from the FPCPolicyElements object. Notice that the FPCPolicyElements object is derived from both the FPCArray object and the FPCEnterprise object.

Gray boxes represent collections and white boxes represent objects. Click boxes at the bottom of the diagram to continue down through the entire hierarchy.

FPCCache Object Model

The following diagram shows the administration objects derived from the FPCCache object. Gray boxes represent collections and white boxes represent objects. Click boxes at the bottom of the diagram to continue down through the entire hierarchy.

FPCProxyClientConfig Object Model

The following diagram shows the administration objects derived from the FPCProxyClientConfig object. Gray boxes represent collections and white boxes represent objects. Click boxes at the bottom level of the diagram to continue down through the entire hierarchy.

FPCPolicies Collection Object Model

The following diagram shows the administration objects derived from the FPCEnterprisePolicies collection. Gray boxes represent collections and white boxes represent objects. Click boxes at the bottom of the diagram to continue down through the entire hierarchy.

FPCServers Collection Object Model

The following diagram shows the administration objects derived from the FPCServers collection. Gray boxes represent collections and white boxes represent objects. Click boxes at the bottom of the diagram to continue down through the entire hierarchy.

FPCCacheConfiguration Object Model

The following diagram shows the administration objects derived from the FPCCacheConfiguration object.

FPCFirewallSessions Object Model

The following diagram shows the administration objects derived from the FPCFirewallSessions collection. Gray boxes represent collections and white boxes represent objects.

FPCWebSessions Object Model

The following diagram shows the administration objects derived from the collection. Gray boxes represent collections and white boxes represent objects.

FPCNetConfig Object Model

The following diagram shows the administration COM objects derived from the FPCNetworkConfiguration object. Gray boxes represent collections and white boxes represent objects. Click boxes at the bottom of the diagram to continue down through the entire hierarchy.


About Administration Scripting

Scripting allows you to use the ISA administration objects to access and control policies and configurations for an enterprise or for any ISA domain array within an organization.

ISA administration scripting has a number of benefits, such as saving time on tasks that are repetitive or need to be carried out on a number of servers or domain arrays. Administration scripting has other advantages:

Simplifies configuration changes: With ISA you do not need to write code that accesses the Registry or Microsoft® Active Directory™ service because the Save and Refresh methods of the COM objects will save configurational changes for you. The objects thereby provide simple and comprehensive access to ISA configuration The objects also use Active Directory in Windows® 2000 when available, while hiding the storage implementation details from the developer.

Maintains consistency: ISA object methods that set the values of multiple related properties with one method call will check whether the combinations of property settings are valid, and return errors if the properties are not set correctly. Consistency is maintained because your scripts do not assign conflicting property settings.

Ensures that services receive changes: Most ISA administration objects have a Save method that stores changes. Services register to detect and use the new settings. This dynamic configuration allows services to receive notification of the changes without requiring the server to be stopped and restarted. Some changes will not take place immediately. For example, if a user is in an FTP session, revoking that user's FTP privileges will not cancel the current session. However, that user will not be able to request another FTP session.

Allows command-line and Windows scripting: Microsoft Windows Script Host is a language-independent scripting host for Microsoft ActiveX® scripting engines. It allows you to run ISA Server administration scripts from both the Windows desktop and the command prompt. For more information about Windows Script Host see MSDN.

Real-time administration: You can create scripts that allow you to query and control the real-time state of your ISA Server domain arrays.

Task Scheduling: Using scripts, tasks that have to be performed on a regular basis can be scheduled to occur automatically. For example, you could create a script that would automatically back up configuration information.

Scripting interfaces: Scripts can be easily incorporated into HTML pages. By incorporating scripts into an HTML page, you can create a scripting interface to ease administrative tasks.

See Also

Cache Administration, ISA Administration Scripting


About the ISA Firewall

The Internet Security and Acceleration (ISA) Server 2000 consists of the Firewall service, application filters, the w3proxy Web proxy service, and Web (ISAPI) filters. An HTTP filter diverts all HTTP requests to the w3proxy service.

The ISA firewall also provides dynamic Internet Protocol (IP) packet filters to evaluate packets, and Secure Network Address Translation (SecureNAT) to enable NAT clients to connect through ISA. Also, ISA Server uses the bandwidth-control functionality of Windows® 2000 Quality of Service (QOS) to allow you to manage bandwidth use.

This section includes the following topics:

  • IP Packet Filtering
  • Secure Network Address Translation
  • ISA Server Services

The Web proxy service includes the ISA cache, discussed in a separate section, About the ISA Cache.


IP Packet Filtering

Internet Protocol (IP) packet filtering intercepts and evaluates packets before they are passed to higher levels in the protocols or to an application. This includes every IP packet, including Transmission Control Protocol (TCP) packets, User Datagram Protocol (UDP) datagrams, and other packet types. IP packet filters can be configured so that only specified packets will be passed through the ISA Server. This provides a high level of security for your network. IP packet filtering can block packets originating from specific Internet hosts and can reject packets associated with many common attacks. IP packet filtering can also block packets destined to any service on your internal network, including the Web proxy , Firewall, World Wide Web (WWW), or SMTP services.

You can create IP packet filters, which filter packets based on service type, port number, source computer name, and destination computer name. IP packets filters are static — communication through a specific port is always either allowed or blocked. Allow filters allow the traffic through, unconditionally, at the specified port. Block filters always prevent the packets from passing through the ISA Server computer.

Packets that are not specifically allowed or blocked are passed to the ISA services at the application level. At the application level, you can create an ISA Server policy, which is a set of rules that specify which communication is allowed. The ISA Server policy specifies the communication that should be allowed or blocked from reaching the Web proxy and ISA Firewall services. Ports are opened for transmission or reception, and then immediately closed after one of the ISA services closes the connection.

Dynamic Packet Filtering

ISA Server supports inbound and outbound IP packet filtering. ISA Server can dynamically determine which packets can be passed through to the internal network's circuit and application layer services. You can configure access policy rules that open ports automatically only as allowed, then close the ports when the communication ends. This process is known as dynamic IP packet filtering. This approach minimizes the number of exposed ports in either direction and provides a high level of problem-free security for your network.

For many application protocols, such as media streaming, dynamic IP packet filtering provides the most secure method to handle dynamically allocated ports.

Intrusions and alerts

ISA Server features an intrusion detection mechanism, identifying when an attack is attempted against your network, and performing a set of configured actions in case of an attack.

To detect unwanted intruders, ISA Server compares network traffic and log entries to well-known attack methods. Suspicious activities trigger alerts — a set of configurable actions. Actions include connection termination, service termination, e-mail alerts, and logging.

ISA Server monitors for the following types of attacks:

  • All-port scan attack
  • Enumerated-port scan attack
  • IP-half scan attack
  • Land attack
  • Ping-of-death attack
  • UDP bomb attack
  • Windows out-of-band attack

For more information, see the ISA Server product documentation.


Secure Network Address Translation

Secure network address translation (SecureNAT) is an extension of the Microsoft® Windows® 2000 NAT driver.

NAT substitutes a global IP address, valid on the Internet, for an internal IP address. This substitution allows multiple hosts with private IP addresses to share a single external (public) IP address, yet remain protected by the ISA Server Firewall service.

ISA Server's SecureNAT feature provides a degree of address transparency for networked clients. NAT is based on an Internet Engineering Task Force (IETF) standard, and substitutes a global IP address that is valid on the Internet for an internal IP address. ISA Server enhances the underlying NAT functionality of Windows 2000 by enabling access control for FTP, ICMP, H.323, and PPTP protocols. NAT also enables rerouting HTTP requests, which can then frequently be satisfied by a local cache, as now occurs with CERN proxy.

SecureNAT provides Internet connectivity for multiple computers that share a single modem and Internet service provider account. SecureNAT functionality lets multiple hosts connect through a single gateway computer to the public Internet. The SecureNAT feature allows a single dial-up or other connection to the public network to serve the entire network, which then allows access to both the Internet and corporate networks for telecommuting and other purposes. Every host on the private network shares one or more global addresses.

If network settings are configured so that the default gateway is the IP address of an ISA Server computer, the NAT substitutes such a globally valid source IP address for the private IP address of a client that originates an outgoing request. The NAT will substitute in the source address of the ISA Server computer in the data packet, because responses must return to the global ISA Server host IP address.

While SecureNAT's transparency eliminates the need to make settings other than that of the default gateway, it is important to note that SecureNAT will not work for all protocols, such as certain gaming protocols, and new protocols, for which no protocol editors exist.

SecureNAT can be used in conjunction with ISA Firewall service in the case of applications with Windows Sockets (Winsock) capabilities. There is no need to perform manual configuration of this functionality, because configuration occurs behind the scenes. Since SecureNAT works with the Firewall service, application filters can work as NAT editors, and NAT clients can be managed by the administrator as Firewall service clients would be. This means that the ISA Server rules and policies can apply to NAT clients.

SecureNAT Considerations

While SecureNAT provides transparency without special client configuration or installation of software on the client and even provides setting of default gateways automatically, NAT has the following limitations:

  • Only IP-based (not user-based) policies can be implemented, because the identity of users is not passed to the ISA Server. This limits policies to those based on the IP address of the client.
  • NAT works only for those protocols explicitly supported by NAT, and may not be used with the majority of protocols that embed IP addresses within packets.

Note to Developers

With SecureNAT, ISA Server extends the underlying NAT functionality of Windows 2000 to the level of the firewall, and thus, to the User mode. An application filter that enables secondary connections for a NAT client takes the place of a NAT editor. Enabling secondary connections for NAT clients through SecureNAT is thus simplified, and you have access to user-mode debugging tools for the development process.

You can develop a application filter that enables secondary connections for a NAT client and that adds functionality equally efficient for Firewall clients and NAT clients. Alternatively, you can develop an application filter to specifically address the secondary connection needs of NAT clients in order for them to work with other application filters, such as those that perform content filtering.

If you create an application that uses a proprietary protocol, you can create an application filter that will enable SecureNAT clients to use that application.

Because SecureNAT functions in User mode and is an integral part of ISA, ISA policy can be applied to NAT clients. With SecureNAT, you can control access to FTP, Streaming Media protocols, and Windows NetMeeting® for H.323. ISA Server's SecureNAT also permits you to reroute HTTP requests, which can then frequently be fulfilled by a local cache. This enhancement boosts HTTP performance and lowers bandwidth requirements.


ISA Server Services

ISA Server acts as a gateway to the Internet, implementing security in three security layers: IP packet filtering, application layer, and circuit layer. ISA Server's multilayered approach is made possible by the services included with ISA Server:

  • The ISA control service. This is responsible for the IP packet filter (enabling, opening static filters, logging), restarting the other services as necessary, generate alerts and run actions and many more.
  • Scheduled cache content download service.
  • Web proxy service. The Web proxy service is implemented at the application level, and works only with application protocols.
  • Firewall service. The Firewall service is implemented at the circuit level.

All the services work with dynamic IP packet filtering, to provide a complete security model.

This section contains the following sections:

  • About the ISA Control Service
  • About the Scheduled Cache Content Download Service
  • About the Firewall Service
  • About the Web Proxy Service


About the ISA Control Service

The ISA control service controls the following ISA functions:

  • IP packet filters, including enabling filters, opening static filters, and logging filters.
  • Restarting other ISA services as necessary.
  • Generating alerts and running actions.
  • Synchronizes each server with the server array. The ISA control service checks the security level of the domain array and applies the same level to the server, updates the client configuration files (msplat.txt and mspclnt.ini), and deletes unused cache files and log files.
  • Controls the other services when dynamic changes occurs that the service does not handle, such as IP packet filter changes, or cache files that are marked unused (with a size equal to 0).


About the Scheduled Cache Content Download Service

ISA Server further extends caching performance with a customizable scheduled downloading feature. You can configure which content ISA Server should precache and schedule when the content should be cached, available for access directly from the ISA Server cache rather than from the Internet. By monitoring and analyzing Internet access, you can determine which Internet objects will be needed and when. Then you can use scheduled downloading to prepare the ISA Server cache accordingly.

The ISA Server scheduled content download feature enables you to download HTTP content directly to the ISA Server cache, upon request or as scheduled. This enables you to update the ISA Server cache with HTTP content that you anticipate will be requested by clients in your organization.

You can use scheduled downloading to schedule downloads of HTTP files from a Web site to a local cache. You can download a single URL, multiple URLs, or an entire Web site according to a schedule you specify.

Note Sites that contain pop-ups, such as those that ask for credentials, or offer installation of language packs, cannot be downloaded by the scheduled cache download service.


About the Firewall Service

The Firewall service is a generic, circuit-level proxy for Windows Sockets (Winsock) applications. The ISA Firewall service makes Telnet, e-mail, news, Microsoft NetShow®, RealNetworks' RealAudio, Internet Relay Chat (IRC), and other Winsock-compatible client applications perform as though they were directly connected to the Internet. The client application makes Winsock application programming interface (API) calls in order to communicate with an application running on an Internet-based host. The ISA Firewall service redirects the necessary functions to the ISA Server computer, thus establishing a communication path from the internal application to the Internet application through the ISA Server computer. This functionality eliminates the need for a specific gateway for each protocol, such as News Simple Mail Transfer Protocol (SMTP), Telnet, or File Transfer Protocol (FTP). The ISA Firewall service allows applications with no built-in support for a proxy to benefit from proxy service without using the protocols.

This section contains the following topics:

  • How the Firewall Service Works
  • Firewall Service
  • About Control Channels
  • Firewall Client
  • Application Filters


How the Firewall Service Works

The Firewall client captures an API call and redirects it to the Firewall service, which makes the actual call. That is, there are actually two connections: one on the private network from the client to the ISA server and one over the Internet from the Internet host to the ISA server.

The Firewall service consists of two parts: a dynamic-link library (DLL) running on the Firewall client and a service running on the ISA Server computer.

Note ISA Server's Firewall service makes use of a Windows Sockets 2.0 layer service provider (LSP) architecture. For more information on LSPs, see MSDN.


Firewall Service

The Firewall service runs as a stand-alone service on Windows 2000. It establishes gateway connections between the Windows Sockets (Winsock) applications on the client and the Internet host. The local network remains secure, because communication is channeled through the ISA server. The Firewall service can be enhanced by using application filters.


About Control Channels

When ISA Firewall client software is installed on the computer, it installs two .dll files. The files intercept Winsock API calls from applications on the client and forward them to the ISA Server computer, using a control channel.

The control channel manages remote Winsock messages, and is designed to do the following:

  • Deliver the Local Address Table (LAT) to the client. The LAT determines whether a destination is on the local network.
  • Establish TCP connections from the client to the ISA server. This channel is used to build the virtual connection while attempting to connect with a remote application.
  • Furnish UDP communications to and from the ISA firewall client and with the ISA Server.

The ISA Firewall client .dll is initialized when the first Winsock connection is attempted. Then a control channel with the ISA Firewall service is established and then designated as active through the channel. Finally, the LAT is copied from the server to determine which networks are on the Internet and which are local.


Firewall Client

The Firewall client component is layered on top of the original Winsock implementation. In platforms that support Winsock 2.0, the client is an LSP. On other platforms, the client setup application renames the original Winsock DLL (wsock32.dll) and installs its own implementation of wsock32.dll.

The Firewall client communicates with the Firewall service using a dedicated connection called the Firewall service control channel. The control channel connection is established the first time it is needed.

When a client application calls a Winsock function, the client DLL intercepts the call and decides based on the specified request, and the firewall service configuration files whether the call is local or remote. Local calls are passed to the original Winsock implementation. Remote calls are redirected to the firewall service.

When a function call is redirected to the proxy, the client component sends a request through the control channel to the Firewall service and waits for a response. The Firewall service checks the request against the ISA Server policy, processes the request on behalf of the client, and returns a reply through the control channel. The reply is then processed by the Firewall client, and translated to a Winsock error code in case of failure.

Note The remote Firewall client software supports basic Winsock 1.0 and Winsock 2.0 functionality. However, the following limitations should be noted:

  • Overlapped I/O on WSARecvFrom — The Winsock API will work, but for a remote socket, the from address that the application will receive is the address of the firewall service's internal socket. However, using a blocking or non-blocking recvfrom, the application will see the actual from address of the internet host that originally sent the packet.
  • Winsock QOS — ISA installs an LSP that supports Quality of Service (QOS) requests. However, for connections made through the Firewall service, Resource Reservation Setup Protocol (RSVP) reservations will not pass through the service.
  • Winsock Name Service Functions are limited — WSALookupService{Begin/Next/End} are implemented, but only resolve queries that would translate into queries using the gethostbyname, gethostbyaddr, getservbyport, or getservbyname functions.


Application Filters

Application filters are extensions of the Firewall service. These filters register for and process Firewall service events. By exposing its COM interfaces to developers, ISA Server allows them to extend its security and functionality. Developers can use these interfaces to extend the security and access control for Firewall service, and to create protocol-specific application filters. These can share the architecture, access control, and administration of the Firewall service. Use of these interfaces is described in Developing Application Filters. Specifically, the interfaces allow a filter to:

  • Receive notifications of special events; for example, when a user connects to a certain remote port.
  • Allow or deny user access to certain operations; for example, binding to a particular port.
  • Examine and possibly modify data that flows through the firewall; for example, in order to perform virus checking.
  • Initiate network operations (proactive caching) through dynamic IP packet filtering.
  • Seamlessly integrate with the ISA Server administration tool.

See Also

Developing Application Filters, Internet Security and Acceleration Reference, Interfaces


About the Web Proxy Service

The Web proxy service (w3proxy) is a Windows 2000 service that supports requests from any browser that conforms to standards of the Conseil Europeen pour la Recherche Nucleaire (CERN). The Web proxy service allows Web access to nearly every desktop operating system, including Windows NT, Windows 95, Windows 98, Windows 2000, Macintosh, and UNIX.

The Web proxy service works at the application level on behalf of an HTTP client requesting an Internet object retrievable through one of the protocols supported by the Web proxy service: FTP, HTTP, HTTPS, and Gopher. Web proxy protects all Web browser access. The Web proxy service operates with a Web proxy client, which can be any client computer that uses CERN-compliant applications and is configured to use the Web proxy service of ISA Server.

Unlike Microsoft Proxy Server 2.0, which implemented the Web proxy as a Web (ISAPI) filter loaded by the local Internet Information Services (IIS) Web server, Web proxy now runs as a Windows 2000 process (W3Proxy.exe). The process can be initialized by starting the Web proxy service. IIS Server can be installed on an ISA Server computer, but this is not required. For more information on IIS and ISA, see Internet Information Services Separation.

You can use the secure Web publishing feature of ISA in conjunction with Internet Information Services (IIS) or other Web servers to publish to the Internet without compromising the security of your internal network. ISA uses Secure Web publishing and reverse hosting to send requests to Web-publishing servers connected behind the ISA proxy computer. ISA server's w3proxy service supports the use of Secure Sockets Layer (SSL), and also supports Web (ISAPI) filters.

The Web proxy service includes the ISA cache, described in About the ISA Cache.


W3proxy Service Clients

Web proxy clients (typically browsers) must be specifically configured to use the ISA Server. When a user requests a Web site, the browser parses the URL. If the name contains "dots" such as a Fully Qualified Domain Name (FQDN), the browser considers the destination to be remote and sends the HTTP request to the ISA Server for processing .


Web (ISAPI) Filters

Web (ISAPI) filters detect and process HTTP events, and can extend the functionality of the w3proxy service. Using the Internet Server application programming interface (API), ISA supports the Web filter extensibility model, which lets third-party developers examine and change the HTTP request and response flow. ISA does not support ISAPI extensions.

For more information about ISA support of Web filters, see Developing Web (ISAPI) Filters for ISA.


Internet Information Services Separation

Unlike Microsoft Proxy Server 2.0, which implemented the Web Proxy service as an ISAPI filter that was loaded by the local IIS Web server, the Web Proxy service now runs as a Windows 2000 service named W3Proxy. The process can be initialized by starting the Web Proxy service. IIS Server can be installed on an ISA Server computer but it is not required.

The incoming Web request and outgoing Web request properties can now run on different TCP ports. For example, by default, ISA Server listens for outgoing Web requests on TCP port 8080, while ISA Server listens for incoming Web requests on TCP port 80. In this way, ISA Server ensures that outgoing Web requests do not interfere with Web publishing on port 80.

If IIS Server is installed on the ISA Server computer, it must be configured not to use the ports that ISA Server uses for outgoing Web requests (by default, 8080) and for incoming Web requests (by default, 80). For example, you can change IIS Server to listen on port 81. Then you can configure the ISA Server computer to direct the incoming Web requests to port 81 on the local IIS Server.

If there is a conflict between ports used by ISA Server and those used by IIS Server, the setup program will stop the IIS publishing service. You can then change IIS Server to listen on a different part and then restart the IIS Server publishing service.

For more information see the ISA product documentation.


About the ISA Cache

Internet Security and Acceleration (ISA) maintains a centralized cache of frequently requested Internet objects that can be accessed by all ISA Server clients. ISA also allows distributed content caching among multiple ISA hosts. Distributed caching may be implemented with domain arrays, chains, or a combination of both.

ISA Server's caching features include:

  • Distributed caching
  • Scheduled content downloading
  • Hierarchical content caching
  • Active caching
  • FTP and HTTP cache support
  • Negative caching

These are described in detail in the ISA product documentation.


ISA Caching Mechanism

In ISA, cached pages are stored immediately in memory to be accessed by clients. A "lazy-writer" approach is used to write the pages to a disk. This approach results in faster cache-availability of the page. There is no direct mechanism for checking whether a page has been cached or written to the disk.

The ISA cache approach thus results in improved cache performance. If the system is shut down, Web objects stored in memory that have not yet been written to a disk must be obtained from the Internet.

The ISA cache functions in both the forward proxy and secure Web publishing scenarios. In the forward proxy scenario, internal Web clients will obtain frequently requested Web objects from the ISA cache. In the secure Web publishing scenario, your most frequently used Web pages will be stored on the ISA cache so that they can be provided more quickly in response to external requests.


Cache Administration

The ISA administration COM objects allow you to administer the cache programmatically, automate administrative tasks related to the cache, and extend cache performance using the FetchUrl method. An introduction to FetchUrl is provided in Extending the Cache.

For more information regarding cache administration see Managing the ISA Server Cache.


Using Internet Security and Acceleration

Microsoft® Internet Security and Acceleration (ISA) Server 2000 is a tool that third-party developers can extend by creating components that work with ISA, such as application filters, administration tools, and Web (ISAPI) filters. For example, a company may develop an application filter that scans for viruses. The filter configuration information should be included with ISA configuration information. When ISA is backed up, the virus-scanning filter configuration data is also backed up. The mechanism for integrating third-party data into ISA is the FPCVendorParametersSets collection.

Developers can also create Microsoft Management Console (MMC) extension snap-ins for components designed to work with ISA, so that relevant property pages will be integrated into the ISA administration tool.

Source Files and Administration Samples Provided with ISA

The msfpccom.idl source file contains the definitions of all ISA administration COM objects.

Within the ISA Software Developer's Kit (SDK), the following topics contain example code that can be copied from the text:

  • Configuring Destination Sets
  • Configuring Schedules
  • Restricting Site Access
  • Adding a Custom Event and Alert

ISA Samples on CD-ROM

In addition to the example code in the SDK, the following samples are on the ISA CD-ROM in the sdk\samples\Admin\Scripts folder. The file name of each sample is the name listed here in the Samples column of the table below and the language extension. See Script Samples for more detailed descriptions.

Samples | Description | Language
AddLATEntry | Shows how to add an IP range to the array LAT | VBScript
CacheSettings | Displays array cache settings | VBScript, JScript
ConstructLAT | Shows how to construct the LAT of an array based on its network interface cards (NICs) | VBScript, JScript
FetchUrl | Causes the Web proxy service to fetch an object and store it in the cache | VBScript
ListServers | Lists servers in a given array | VBScript, JScript
PluginList | Lists the plug-ins of an array | VBScript, JScript
SetCache | Sets the cache | VBScript
SetUpstreamRouting | Shows how to set up upstream routing to another server | VBScript
ShowAllProtocolRules | Lists all protocol rules of an array | VBScript, JScript
ShowAllRoutingRules | Lists all routing rules of an array | VBScript
StaticFilter | StaticFilter demonstrates how to create a static packet filter, which allows NTP communication with the ISA Server computer. NTP uses the UDP protocol and Port 123. | VBScript

Note The JScript samples have limited functionality compared to the corresponding VBScript samples. The major difference is that JScript will always use the first array in a network, whereas VBScript will ask the user for the array name.

This section, Using the ISA SDK, contains the following topics:

  • Extending ISA Storage
  • Adding a Custom Event and Alert
  • ISA Administration Scripting
  • Extending the ISA Administration Tool
  • Developing Application Filters
  • Developing Web (ISAPI) Filters for ISA
  • Extending the Cache


Extending ISA Storage

This section describes how to add extensions to Internet Security and Acceleration (ISA) Server 2000 using the FPCVendorParametersSets collection.

The vendor component must use the ISA central configuration management facilities to store its configuration. The facilities hide the storage location (local or Microsoft® Active Directory™), and provide support for promotion to Active Directory, central backup-and-restore capabilities, and sharing with all array members. A vendor can create new objects or associate additional information to system-defined objects by means of the FPCVendorParametersSets collection.

For example, an application filter can be added to ISA using the FPCVendorParametersSets collection. This filter will then save the Multipurpose Internet Mail Extensions (MIME) data types that it needs to filter; this data will be stored by means of the collection's Save method and associated with that filter. After this extension is made to ISA, the vendor-specific data will be backed up with all other ISA data.

See Also

FPCVendorParametersSet


Adding a Custom Event and Alert

The alert service of Internet Security and Acceleration (ISA) can be configured to signal an alert when an event occurs that an administrator should be aware of, such as running out of disk space. The way ISA handles this and other events can be customized through the administration COM objects.

The ISA administration tool is the simplest means of adding a custom alert. The actions to be taken in response to a new alert can be customized easily by using the objects. Examples of these actions are sending e-mail, issuing a command, and writing to a log.

This topic describes the entire process of adding a custom event and alert to ISA. This is a step-by-step process, with examples in Visual Basic® Scripting Edition code.

For this example, the added event will signify attacks related to the Domain Name System (DNS). There are three types of events: DNS Host Name overflow, DNS Length Overflow, and DNS Zone High Port.

Use the following steps to add a custom event and alert to ISA:

  1. Add a new event definition using the EventDefinitionSet collection, as described in Adding a Custom Event.
  2. Define a new alert for this event through the ISA administration tool, as described in Adding a Custom Alert.
  3. Signal the new event, as described in Signal the Event.

Note The ISA administration objects can be used with any language that supports COM. You need not to use Visual Basic® Scripting Edition (VBScript) to add a custom event or alert.


Adding a Custom Event

ISA events describe conditions that require the attention of an administrator, such as a disk-full event. Following is an example of adding a new event definition to the FPCEventDefinitions collection using VBScript code. In this example, the additional-keys table is used. Additional keys serve as a way to subdivide event objects into related subevents; for example, subdividing a disk-full event into log-disk-full or system-disk-full subevents. This allows for different alerts that are specific to subevents or one alert that is specific to all subevents.

Example

Sub AddEvent()
Dim AdditionalKeys(3)
Dim eventdefs As FPCEventDefinitions
Set eventdefs = CreateObject("FPC.Root").Arrays.GetContainingArray.PolicyElements.EventDefinitions
eventdefs.Refresh            ' Update object
    EventGUID = "{DF2D1202-929C-11d2-872C-00A02453BDDE}"

    ' Define a new custom event

    ' Fill in table of additional keys
    AdditionalKeys(0) = "All DNS attacks"
    AdditionalKeys(1) = "DNS Host Name overflow"
    AdditionalKeys(2) = "DNS Length Overflow"
    AdditionalKeys(3) = "DNS Zone High Port"

    Set MyEvent = eventdefs.Add("DNS Attack", EventGUID, AdditionalKeys)

    MyEvent.Save            ' Save changes
End Sub

In the line of code

Set MyEvent = eventdefs.Add("DNS Attack", EventGUID, AdditionalKeys)

from the example, the third parameter is the table of additional keys for this particular event.

See Also

FPCEventDefinition


Adding a Custom Alert

The FPCAlert object defines an alert. When a specific event occurs, this object determines the actions that ISA takes in response to that event. The FPCAlert object also defines the three thresholds that determine when actions will be taken. Alerts allow ISA to notify an administrator when certain events take place. The administrator can decide in advance which actions to take. You can access the properties of the actions to be taken through the FPCAlertActions collection.

This topic explains how to add a new alert to ISA. To a filter developer, adding a new alert is not necessary, but it could be useful for testing.

The easiest way to add a new alert to ISA is from the ISA administration tool. To add an alert in this manner, open the ISA administration tool. Right-click the Alerts node in the console tree. From the menu, select New and Alert. From there, follow the instructions in the wizard.

See Also

FPCAlertAction


Signal the Event

This topic shows the signaling of the event. The variable below 'AdditionalKey' is the index into the additional-keys table, and holds the value of 2, signifying that this event is "DNS Length Overflow". The following code assumes that the "DNS Length Overflow" event occurred.

Note SignalEvent will usually be called from C++ code. VBScript, as in the example below, is likely to be used for testing purposes.

Example

Sub SignalEvent()
    Set AlertNotification = CreateObject("FPC.AlertNotification.1")

    Dim SysLogEventStrings(1)

    EventGUID = "{DF2D1202-929C-11d2-872C-00A02453BDDE}"
    ServerName = Empty   'Meaning current machine
    AdditionalKey = 2    'Index in AdditionalKeys table specifying that "DNS Length Overflow" attack occurred.

    ' This parameter contains data needed for system log reporting
    SysLogEventType = 0
    SysLogEventCategory = 2
    SysLogEventSourceName = "ISS Filter"
    SysLogEventID = &H80000006
    'Assume that &h80000006 is ID of resource string such as: "DNS attack of type '%1' detected"
    SysLogEventStrings(0) = "DNS Length Overflow"  ' Will be substituted in the string above
   SysLogEventData = ContentOfPacket

   AlertNotification.SignalEvent EventGUID, ServerName, AdditionalKey, _
   "DNS attack detected", "ISS Filter detected a DNS attack", _
   SysLogEventID, SysLogEventSourceName, SysLogEventStrings, SysLogEventData, _
   SysLogEventCategory, SysLogEventType
End Sub ' SignalEvent

See Also

FPCAlertNotification


ISA Administration Scripting

The ISA administration object model gives developers a mechanism to extend ISA functionality. Scripting allows you to use the ISA administration COM objects to access and control any ISA array within an organization. The administration objects allow for automation of everything done using the ISA administration tool. This capability allows administrators to create scripts to automate repetitive tasks requiring the use of the administration tool; these scripts can then be included in batch files. By programming with the same administration objects that ISA itself uses, developers can provide persistent, and configurable, data storage for their programs, and can have the ISA Server notify programs when the configuration data has changed.

Using the Microsoft® Management Console (MMC), developers can also customize the administration tool by adding new property pages, menus, toolbars, and buttons, and by extending the name space. See Extending the ISA Administration Tool for examples of ISA administration tool customization.

The following topics demonstrate how all administrative tasks carried out with the ISA administration tool can be automated through the use of the administration objects.

  • Getting Started with Administration Objects
  • Constructing the Local Address Table
  • Adding a Packet Filter
  • Configuring Arrays
  • Configuring Schedules
  • Configuring Destination Sets
  • Restricting Site Access
  • Adding Internet Access for New Users
  • Backup and Restore
  • Enterprise and Array Policy
  • Adding a Dialup Entry
  • Scenarios
  • Script Samples


Getting Started with Administration Objects

To start using the administration COM objects, set up your development environment through either of the following procedures, depending on whether you use Microsoft Visual Basic® or C++. You must have ISA installed for the procedures to work.

To start using the administration objects with Visual Basic

  1. Open the Microsoft Visual Basic program and open a new Standard EXE project.
  2. Go to the Project menu at the top of the window.
  3. Select References.
  4. Select Microsoft Firewall Proxy and Cache Administration Library from the dialog box that appears. This library is defined in msfpccom.idl, which is a file included with ISA. Therefore, you need to have ISA installed for access to this library. This will make all the administration COM objects available to you.
  5. Create the root ISA object as described in Creating the Root ISA Object.
  6. Write your program. See Add a Schedule for an introductory example.
  7. To apply your changes, you must call the Save method as described in Saving and Refreshing Objects.

If you are using Visual Basic Scripting Edition (VBScript), and would like to use enumerated types, see Using Enumerated Types in Scripts.

Note Unless otherwise noted, the examples in this section are written in Visual Basic, but you can use any language to script with the administration objects. If, for example, you script with VBScript, you can use any text editor to create the scripts.

To start using the administration objects with C++

Include the file msfpccom.dll with the following line of code:

#import "msfpccom.dll"

The file msfpccom.idl contains the definitions of the ISA administration objects.

This section contains the following topics:

  • Creating the Root ISA Object
  • Saving and Refreshing Objects
  • Using Enumerated Types in Scripts
  • Managing Dependent Objects
  • Managing Collections


Creating the Root ISA Object

You can access all ISA administration COM objects through a single root object. You must first create this root object and then use its properties to access subordinate objects in the object model. All server arrays and other configurational settings are accessed through the root object.

To create this root object in a scripting language such as VBScript or Microsoft JScript®, use the CreateObject function. Use the class name "FPC.Root", as in these examples:

  • VBScript
    Set objFPC  = CreateObject ("FPC.Root")
  • JScript
    objFPCRoot = CreateObject ("FPC.Root");

When creating the root object in Visual Basic, use the following:

Dim objFPC As New FPCLib.FPC

CreateObject is also available to Visual Basic programmers and so, alternatively, the following can be used:

Dim objFPC
Set objFPC = CreateObject("FPC.Root")

Creation of the root objectis the first step in all ISA scripts. If you are using Visual Basic, you must have the Microsoft Firewall Proxy and Cache Administration Library selected as a project reference to create this object. Select the library in the Project References menu of the Visual Basic editor.


Saving and Refreshing Objects

Many ISA administration COM objects have methods you can use to save their settings to persistent storage or to refresh their settings from values in persistent storage.

Saving Objects

The Save method stores all settings of an object in persistent storage. It is important to note that you can save no changes unless you call the Save method. For example, if you change the value of a property, you must explicitly save the changes to the object, or the change will not be written to persistent storage.

In the following example, the changes will not be saved until the Save method is called on the last line of code.

Dim objFPC As New FPCLib.FPC
Dim FPCArraysName As String
Dim objFPCArrays As FPCArrays
Set objFPCArrays = objFPC.Arrays
objFPCArrays.CurrentArray.Name = "CurrentArray"
' no changes saved yet
objFPCArrays.Save
' change saved

Note Some objects do not have a Save method. To save these objects, invoke the Save method of a parent of the object in the hierarchy.

For an example, see the FPCArrays.Save method.

Refreshing Objects

If you need to abandon changes you've made to an object — while preserving the object in memory — use the Refresh method. The Refresh method reads the last saved values from persistent storage and applies them to the object and its subordinate objects.

The Refresh method retrieves and applies the last saved settings for an object and any subordinate objects. Use the Refresh method to be sure you have the current values for an object and its subordinate objects.

The Refresh method overwrites any changes made but not saved when it applies values from persistent storage. This can be useful when you want to cancel changes that have been made but not yet saved with the Save method.

In the following example the value of objFPCArrays.CurrentArray.Name never changes because the Save method is not called.

Dim objFPC As New FPCLib.FPC
Dim FPCArraysName As String
Dim objFPCArrays As FPCArrays
Set objFPCArrays = objFPC.Arrays
objFPCArrays.CurrentArray.Name = "CurrentArray"
' no changes saved yet
objFPCArrays.Refresh
' change above not saved


Restarting Services after Configuration Changes

Many configurations changes that you make require the restarting of the Firewall service and/or the W3proxy (Web proxy) service. If you make a change by using a script, your script can use the FPCArray.SendRestartNotification method to stop and start the relevant service. Otherwise, the service can be stopped and started through the ISA administration tool, as described in the ISA Server documentation.

The following table summarizes the requirements.

Action | Service to be restarted
Adding, removing, enabling or disabling an application filter | Firewall service
Reducing cache size | W3proxy service
Removing a disk from the cache | W3proxy service
Changing the LAT so that the Network Interface Card (NIC) internal/external state changes | Firewall and W3proxy services
Enabling and disabling of packet filtering | Firewall and W3proxy services
Enabling or disabling a NIC | Firewall and W3proxy services
Changing the IP address of a NIC | Firewall and W3proxy services
Making changes to the routing table | Firewall service
Changing Web filter configuration | W3proxy service
Changing the port numbers on which the W3proxy service listens | W3proxy service
Editing client configuration (mspclnt.ini) | Firewall service
Updating SSL certificates | Firewall service


Using Enumerated Types in Scripts

Unlike Visual Basic or Microsoft Visual C++®, scripting languages, such as VBScript or JScript, do not support the use of enumerated values.

For this reason the ISA SDK includes two files that define the enumerated values used in ISA as constants.

The file fpccfg.vbs defines enumerated values in VBScript format.

The file fpccfg.js defines enumerated values in JScript format.

To use enumerated types when composing VBScript or JScript script files, copy the relevant constant definitions from the relevant fpccfg file to the constant declarations in your code.

<script language="JScript" src="fpccfg.JS">

For example, including the following code in the declarations section of your script

Const prxInbound = 0
Const prxOutbound = 1
Const prxTCP = 0
Const prxUDP = 1

allows you to write the following:

Set MyProtocol = Protocols(1)
MyProtocol.SetInitialConnection   prxInbound,PrxTcp,344

If you always declare the appropriate constants in your declarations section at the beginning of each script, you can use enumerated types as you use them in C++ programs.

Alternatively, you can achieve the same effect by hard coding the values, as shown in the following code.

Set MyProtocol = Protocols(1)
MyProtocol.SetInitialConnection   1,0,344

These two lines will perform the same task without the use of enumerated types.

When composing Windows Script (WS) or Windows Script File (WSF), which are Windows Script Host files, or when embedding scripts in HTML files, the constants files can be included by the following statement. For more information about Windows Script Host, see the MSDN library.


Managing Dependent Objects

Many ISA objects depend upon other objects. This means that you access dependent objects through the properties of their parent object. Keep the following considerations in mind as you manage these dependent objects in your code:

  • When adding an object that contains a reference to another object or when modifying the name of the referenced object, ISA attempts to verify the existence of the referenced object. If the referenced object cannot be verified, the operation fails.
  • For example, the following code
    MySiteAndContentRule.SetDestination fpcDestinationSet, "Sports Destinations", fpcArrayScope

    adds a new destination set to a site and content rule. This code fails if the FPCDestination object named "Sports Destinations" has not been previously created. See Restricting Site Access for a fuller example of adding a destination set to a site and content rule.

  • When removing an object that is referenced by another object, ISA checks all instantiated objects to learn whether there are other references to the deleted object. If such references exist, the operation fails.

For example, if the FPCDestination object named "Sports Destinations" is referenced by more than one FPCSiteAndContentRule object, code that removes the destination set will fail. If no other object references the destination set, "Sports Destinations" will be removed successfully.


Managing Collections

A collection is an object that holds many individual objects of the same type. Usually, the name of the collection will be the plural of the name of the individual object types within the collection; for example, the FPCListenEntries collection holds FPCListenEntry objects.

Collections allow you to quickly assign settings to multiple objects of the same type with a script. For example, a collection is used to hold the entries in the ISA Local Address Table (LAT), in the form of FPCLATEntry objects. You can easily populate or export the LAT table with a simple script. See the following topic, Collection Methods and Properties, for specific method and property information.

ISA administration object collections do not support nested For Each loops on the same collection object. For example, the following nested loops will not work because both loops operate on the same collection object:

For Each Rule1 in Array.Proxy.SiteAndContentRules
    For Each Rule2 in Array.Proxy.SiteAndContentRules
        MsgBox Rule1.Name & Rule2.Name
    Next
Next

The following pair of nested For Each loops will work because each loop applies to a different collection object:

For Each Array in Arrays
    For Each Rule in Array.Proxy.SiteAndContentRules
        MsgBox Rule.Name
    Next
Next


Collection Methods And Properties

All objects that are a part of a collection have a similar set of methods and properties, which are all or a combination of the following.

Method | Description
Save | Saves all the objects within the collection to persistent storage. Modifications made to the collection will not be saved until after this method is called. The Save method is recursive, so calling the Save method of the collection will save every object within the collection.
Refresh | Reads the latest saved configuration settings from persistent storage and applies them to the object collection. The Refresh method does not check whether there are any unsaved changes made to the objects, so all changes made after the last Save method call will be lost. The Refresh method is useful when you want to cancel changes that have been made but not yet saved with the Save method.
Add | Adds an object to the collection, and returns a reference to the newly created object. This method takes a string parameter that identifies the new object. The string parameter can be used later to retrieve the object using the Item method. To save this new object to persistent storage, call the Save method.
Remove | Removes an object from the collection. This method takes a string parameter or index of the object to be removed from the collection.
Item | Returns the given object from the collection. This method retrieves an object by an index that is an integer value, or by the name of the object, which is a string value.

Property | Description
Count | Returns an integer value of the number of objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading of custom data into the collection's storage. The VendorParametersSets property is designed to integrate third-party extensions into ISA.

While most collections of objects work in the same way, see individual collection reference pages for particular descriptions.


Constructing the Local Address Table

The Local Address Table (LAT) consists of a series of IP address ranges that define your internal network address space. Typically, the LAT contains all IP addresses associated with the internal network cards on the ISA Server computer, in addition to the private IP address ranges defined by the Internet Assigned Numbers Authority (IANA). For more information see the ISA product documentation.

You can use the ISA administration COM objects to build the LAT. Following is a sample script you can use to construct the LAT.

Sample Script

ConstructLAT.js contains JScript code that constructs a LAT. You can find this script in the Samples folder on the CD-ROM:

WScript.Echo ("About to create a new LAT");
FPC = WScript.CreateObject("FPC.Root");
oLAT = FPC.Arrays.CurrentArray().NetworkConfiguration.LAT;

oLAT.Clear(); // Clear all of the LAT

// Clear the Adapters selections:
oServer = FPC.Arrays.CurrentArray().Servers.GetContainingServer();
c = oServer.AdapterList.Count;
for (i=1; i<=c; i++)
   //oLAT.AdapterList(i).Selected = false;
   oServer.AdapterList(i).Selected = false;

// Select the last adapter:
oServer.AdapterList(c).Selected = true;

// Create the LAT from the selected adapter:
oLAT.AddFromSelectedAdapters(oServer.Name);

// Save the new LAT:
oLAT.Save();
WScript.Echo ("Done");


Adding a Packet Filter

ISA Server's packet-filtering features allow you to control the flow of information to and from ISA Server. With packet filtering, you can intercept and either allow or block packets destined for specific computers on your corporate network.

You can use the administration COM objects to add and configure packet filters. This is done with the FPCIpPacketFilter object.

The following example adds a packet filter that applies to all the servers within the array arr:

' this code creates a static filter for a service that is running
' on the ISA server and needs to connect to
' NTP server on the Internet at known address.

Dim objFPC As New FPCLib.FPC
Dim arr As FPCArray
Dim pf As FPCIpPacketFilter
Set arr = objFPC.Arrays.CurrentArray
Set pf = arr.ArrayPolicy.IpPacketFilters.Add("NetTime")
pf.Description = "NTP filter for My App"

' apply to all servers in the array
pf.AllServers = True
pf.FilterKind = fpcAllowingPacketFilter
pf.FilterType = fpcCustomFilterType
pf.ProtocolNumber = 17

' allow both send and receive
pf.PacketDirection = fpcPfDirectionIndexBoth
' application runs on the ISA Server computer
pf.SetLocalHost fpcPfDefaultProxyExternalIp
pf.LocalPortType = fpcPfDynamicPort

' connecting to a well-known server on the Internet
pf.RemotePortType = fpcPfFixedRemotePort
pf.RemotePortNumber = 123
pf.SetRemoteHost fpcPfSpecificProxyIp, "123.21.32.11", "255.255.255.255"
pf.LogMatchingPackets = False
' enable the filter:
pf.Enabled = True
' save the changes
arr.Save True

See Also

FPCIpPacketFilters


Configuring Arrays

Setting up a network can involve configuring many servers. With ISA, you can configure multiple servers at the same time through the array-level properties and methods of the FPCArray object, which is a member of the FPCArrays collection. ISA arrays are set up programmatically through individual FPCArray objects.

Each ISA array is a set of servers that have a similar configuration and share various resources to increase efficiency. For example, servers in an array share cached Web pages, so that a client attached to one of the computers benefits from pages cached on all of them.

The FPCArrays collection is a property of the ISA root object.

You can obtain a reference to a FPCArray object using either of two methods of the FPCArrays collection:

  • Item method
  • CurrentArray method

The Item method of the FPCArrays collection returns a reference to any array you identify by index or name. Here is a VBScript example:

Set objMyArray = objFPCRoot.Arrays(1)

The CurrentArray method of the FPCArrays collection returns a reference to the current array. The current array is the server array containing the server that executes this code. You can quickly obtain a reference to the current array using code similar to this:

Set objCurArray = objFPCRoot.Arrays.CurrentArray

The FPCArray object has properties that provide access to other parts of the administration object model, a factor that can be useful when setting up a network. The following table lists the properties that provide references to other objects and the objects returned.

Property | Returns a reference to
Alerts | FPCAlerts collection
Cache | FPCCache object
Logging | FPCLogs collection
NetworkConfiguration | FPCNetworkConfiguration object
ArrayPolicy | FPCArrayPolicy object
ProxyClientConfig | FPCProxyClientConfig object
PolicyElements | FPCPolicyElements object
Servers | FPCServers collection
VendorParametersSets | FPCVendorParametersSets collection

See Also

ISA Array Examples


ISA Array Examples

The following code uses the FPCArray.Servers property to return the name of an individual server.

Dim objFPC As New FPCLib.FPC
Dim serverName As String
Dim objFPCArray As FPCArray
Set objFPCArray = objFPC.Arrays(1)
serverName = objFPCArray.Servers(1).Name
MsgBox serverName

The following piece of code retrieves the name of the containing array using the CurrentArray method.

Dim objFPC As New FPCLib.FPC
Dim CurrentArray As String
Dim objFPCArrays As FPCArrays
Set objFPCArrays = objFPC.Arrays
CurrentArray = objFPCArrays.CurrentArray.Name
MsgBox CurrentArray


Configuring Schedules

You can use the ISA administration COM objects to add, modify, or delete a schedule template. Each ISA schedule is represented by a FPCSchedule object within the FPCSchedules collection.

This section contains the following topics:

  • Add a Schedule
  • Modify a Schedule


Add a Schedule

The schedules collection is accessed through the ScheduleTemplates property of the FPCPolicyElements object, as shown here:

Dim objFPC As New FPCLib.FPC
Dim MySchedules As FPCSchedules
Set MySchedules = objFPC.Arrays.CurrentArray.PolicyElements.Schedules

The following is a portion of Visual Basic code that adds a new schedule template called "Extended Work Hours", which includes all hours on all days:

Dim objFPC As New FPCLib.FPC
' declare schedule collection
Dim MySchedules As FPCSchedules
' declare schedule object
Dim objNewSchedule As FPCSchedule
' get the schedule collection of the current array
Set MySchedules = objFPC.Arrays.CurrentArray.PolicyElements.Schedules
' Add new Schedule
Set objNewSchedule = MySchedules.Add("Extended Work Hours")
' Set the Schedule days
objNewSchedule.Set fpcALL_WEEK, fpcALL_DAY
' save your changes
MySchedules.Save

Note that the above schedule will not be saved to persistent storage until the last line of code, where the Save method is called.

See Also

FPCSchedule, Modify a Schedule


Modify a Schedule

The following portion of Visual Basic code modifies the schedule template example shown in Add a Schedule using the UnSet method of the FPCSchedule object. The schedule "Extended Work Hours" is changed so that it includes all hours of the day, but only the days Monday through Friday. This is done by unsetting the days Saturday and Sunday:

Dim objFPC As New FPCLib.FPC
' declare schedule collection
Dim MySchedules As FPCSchedules
' declare schedule object
Dim MySchedule As FPCSchedule
' get the schedule collection of the current array
Set MySchedules = objFPC.Arrays.CurrentArray.PolicyElements.Schedules
' find "New Extended Schedule"
Set MySchedule = MySchedules("Extended Work Hours")
' remove Saturday and Sunday from the schedule
MySchedule.Unset fpcSAT, fpcALL_DAY
MySchedule.Unset fpcSUN, fpcALL_DAY
' save changes
MySchedules.Save

Again, note that the above changes will not be saved to persistent storage until the last line of code, where the Save method is called.

The following topic, Configuring Destination Sets, shows the addition of a new set of forbidden destinations to the FPC destination sets collection. The next section, Restricting Site Access, shows how to restrict site access through a new site and content rule. The new site and content rule applies to both the schedule created in this example, and the forbidden sites added in the section Configuring Destination Sets.

See Also

FPCSchedule, Add a Schedule


Configuring Destination Sets

A destination set is a set of destinations that can be accessed by means of the proxy. Single destinations are grouped in a FPCDestinationSet collection that can be used to define of site and content rules, publishing rules, bandwidth rules, or routing rules. For example, you can create a destination set that contains restricted sport sites, and can define a site and content rule that prohibits access to these destinations during work hours.

The FPCDestinationSets collection is accessed through the DestinationSets property of the FPCPolicyElements object, as shown here:

Dim objFPC As New FPCLib.FPC
Dim MyDestinationSets As FPCDestinationSets
Set MyDestinationSets = objFPC.Arrays.CurrentArray.PolicyElements.DestinationSets

A destination consists of two parts — a host description and a path within this host. For example, in the destination "www.microsoft.com/scripting", "www.microsoft.com" is the host and "/scripting" is the path. If the path is empty, the destination set defines the entire domain. A path within the host is only relevant when using the HTTP protocol. A host can be specified by a domain name, an IP address, or an IP range denoted by a From and To pair of settings.

You can add, delete, and modify destination sets by using the COM objects.

  • Add a Destination Set
  • Modify a Destination Set


Add a Destination Set

The following is a portion of Visual Basic code that adds a new destination set called "Sports Sites", including the site "www.sports.mircrosoft.com", to the destination sets collection:

Dim objFPC As New FPCLib.FPC
' declare the destination sets collection
Dim MyFPCDestinationSets As FPCDestinationSets
' declare the destination set collection
Dim MyFPCDestinationSet As FPCDestinationSet
' declare the destination object
Dim MyFPCDestination As FPCDestination
' set the destination sets to current array
Set MyFPCDestinationSets = objFPC.Arrays.CurrentArray.PolicyElements.DestinationSets
' add a new set to the collection
Set MyFPCDestinationSet = MyFPCDestinationSets.Add("Sports Sites")
' add a new destination to the set
Set MyFPCDestination = MyFPCDestinationSet.Add("www.sports.microsoft.com")
MyFPCDestinationSets.Save
' save your changes
MyFPCDestinationSets.Save

Note that the additional destination set above will not be saved to persistent storage until the last line of code, where the Save method is called.

See Also

FPCDestinationSet, Modify a Destination Set


Modify a Destination Set

The ISA administration COM objects also permit programmatic modification of existing destination sets The following is a portion of Visual Basic code that modifies the destination set from above, adding the sites "www.mysports.microsoft.com", "www.mysport.microsoft.com", and "www.sport.microsoft.com" to the destination set "Sports Sites":

Dim objFPC As New FPCLib.FPC
' declare the destination sets collection
Dim MyFPCDestinationSets As FPCDestinationSets
' declare the destination set collection
Dim MyFPCDestinationSet As FPCDestinationSet
' declare the destination object
Dim MyFPCDestination As FPCDestination
' set the destination sets to current array
Set MyFPCDestinationSets = objFPC.Arrays.CurrentArray.PolicyElements.DestinationSets
' find set "Sports Destinations"
Set MyFPCDestinationSet = MyFPCDestinationSets.Item("Sports Sites")
  'make adjustments to destination here
  Set MyFPCDestination = MyFPCDestinationSet.Add("www.mysports.microsoft.com")
  Set MyFPCDestination = MyFPCDestinationSet.Add("www.mysport.microsoft.com")
  Set MyFPCDestination = MyFPCDestinationSet.Add("www.sport.microsoft.com")
'save changes
MyFPCDestinationSets.Save

The preceding code can be used in the context of a program or script that runs every day and adds new forbidden destinations to existing forbidden destination sets. If, for example, an administrator receives a daily list of forbidden sites from an outside service, this use of the objects automates the task of importing the new forbidden destinations.

The next topic, Restricting Site Access, shows how to restrict site access using a new site and content rule. The rule applies both to the forbidden sites added in the preceding example, and to the schedule added in the topic Add a Schedule.

See Also

FPCDestinationSet, Add a Destination Set


Restricting Site Access

Site access is restricted through the use of a site and content rule. Each site and content rule is represented by a FPCSiteAndContentRule object, and accessed through the FPCSiteAndContentRules collection. A site and content rule defines actions that the proxy will take when specific users attempt to access specific sites or content through the proxy.

  • Add a Site and Content Rule
  • Modify a Site and Content Rule


Add a Site and Content Rule

The following is a portion of Visual Basic code that adds a new site and content rule called "Workday Site Restriction". It refers to the "Extended Work Hours" schedule, which you can see in Add a Schedule. The example here also refers to the destination set "Sports Sites" that appeared in the example in Add a Destination Set.

Dim objFPC As New FPCLib.FPC
' declare collection
Dim MySiteAndContentRules As FPCSiteAndContentRules
' declare rule object
Dim objNewSiteAndContentRule As FPCSiteAndContentRule
' get the rule collection of the current array
Set MySiteAndContentRules = objFPC.Arrays.CurrentArray.ArrayPolicy.SiteAndContentRules
' Add new rule object
Set objNewSiteAndContentRule = MySiteAndContentRules.Add("Workday Site Restriction")
objNewSiteAndContentRule.Description = "Deny sports sites"
objNewSiteAndContentRule.SetDestination FPCDestinationSet, "Sports Sites"
objNewSiteAndContentRule.SetSchedule "Extended Work Hours", fpcArrayScope
objNewSiteAndContentRule.Action = fpcRuleActionDeny
' save your changes
MySiteAndContentRules.Save

Note that the changes will not be saved to persistent storage until the last line of code, where the Save method is called.

See Also

FPCSiteAndContentRule Object, Modify a Site and Content Rule


Modify a Site and Content Rule

The following is a portion of Visual Basic code that modifies the new rule explained in the previous topic, Add a Site and Content Rule. The modification changes the rule so that it redirects the user to a specific URL after denying the request, rather than merely denying the request. This URL could contain, for example, the company policy toward accessing sports sites during work hours.

Dim objFPC As New FPCLib.FPC
' declare rules collection
Dim MySiteAndContentRules As FPCSiteAndContentRules
' declare rule object
Dim MySiteAndContentRule As FPCSiteAndContentRule
' get the rule collection of the current array
Set MySiteAndContentRules = objFPC.Arrays.CurrentArray.ArrayPolicy.SiteAndContentRules
' find rule
Set MySiteAndContentRule = MySiteAndContentRules("Workday Site Restriction")
  ' change rule values here
  MySiteAndContentRule.SetRedirectUrl ("www.microsoft.sports.policy.com")
  MySiteAndContentRule.Action = fpcRuleActionRedirect
' save your changes
MySiteAndContentRules.Save

See Also

FPCSiteAndContentRule Object


Adding Internet Access for New Users

You can add new users to ISA by means of the FPCAccounts collection. Each group of FPCAccount objects holds a set of accounts that can be associated with a site and content rule or a protocol rule. The FPCSiteAndContentRule object represents a site and content rule, and the FPCProtocolRule object represents a protocol rule. You use protocol rules and site and content rules to restrict Internet access for a group of ISA accounts.

The following code adds a new ISA account that represents a new user:

' add new user account
Dim objFPC As New FPCLib.FPC
Dim MyFPCAccounts As FPCAccounts
Dim MyNewFPCAccount As FPCAccount
Set MyFPCAccounts = objFPC.Arrays.CurrentArray.ArrayPolicy.SiteAndContentRules(1).AppliesToAccounts
' add new user account to collection
Set MyNewFPCAccount = MyFPCAccounts.Add("REDMOND\USER", fpcInclude)

An ISA user's Internet access is governed by protocol rules, site and content rules, and schedules. To enable the user to have appropriate levels of Internet access, appropriate rules must apply to this ISA account.

The next topic Applying Rules to User Accounts expands on the preceding code example by adding a new user and applying appropriate rules to the new user. This topic also expands on the topics: Configuring Schedules, Configuring Destination Sets, and Restricting Site Access.


Applying Rules to User Accounts

A new user can be added to ISA through the administration COM objects, as shown in the previous topic, Adding Internet Access for New Users. You can also apply rules to a new-user account by means of the objects. One way to control Internet access is with protocol rules. A protocol rule defines a set of protocols that are allowed to certain users at certain times. These times are defined by a schedule. Unlike site and content rules, protocol rules always define what is allowed rather than what is forbidden.

The following example adds a new user and applies the site and content rule "Workday Site Restriction" to the new ISA account.

Dim objFPC As New FPCLib.FPC
' get site and content rule
Dim MySiteAndContentRules As FPCSiteAndContentRules
Dim objNewSiteAndContentRule As FPCSiteAndContentRule
Set MySiteAndContentRules = objFPC.Arrays.CurrentArray.ArrayPolicy.SiteAndContentRules
Set objNewSiteAndContentRule = MySiteAndContentRules.Item("Workday Site Restriction")
' add new user
Dim MyFPCFPCAccounts As FPCAccounts
Dim MyNewFPCAccount As FPCAccount
' AppliesToAccounts returns accounts collection for this rule
Set MyFPCAccounts = objNewSiteAndContentRule.AppliesToAccounts
' add new account to collection
Set MyNewFPCAccount = MyFPCAccounts.Add("REDMOND\USER", fpcInclude)
' added rule will apply to new user
' save your changes
objNewSiteAndContentRule.Save

The following code applies this site and content rule to the new account during the schedule "Extended Work Hours":

MySiteContentRule.SetSchedule "Extended Work Hours", fpcArrayScope
MySiteContentRule.Save  ' save your changes

See the topic Add a Schedule for an example of adding the schedule "Extended Work Hours".

See Also

FPCAccount, FPCSiteAndContentRule


Backup and Restore

An ISA administrator can back up all ISA settings of a specified array through the administration tool or through a program or script that uses the administration COM objects. The FPCArray.Backup method will back up all settings of an array, and the FPCArray.Restore method will restore all previously saved settings to an array. The Backup and Restore methods always cover all settings in a specific array.

  • Using the Backup Method
  • Using the Restore Method


Using the Backup Method

The Backup method backs up the current array data to a specific file. The Restore method can then be used to read the backed up data at a later time, and return the stored configurational settings to the array.

The following example backs up the current array to a file called "backup file".

Example

Dim objFPC As New FPCLib.FPC
Dim objFPCArray As FPCArray
Set objFPCArray = objFPC.Arrays.CurrentArray
objFPCArray.Backup "backup file", "first backup"

See Also

Using the Restore Method


Using the Restore Method

The Restore method restores the settings stored in a file to the array, overwriting the array's previous settings.

The following example uses the Restore method to restore the current array settings from the file "backup file":

Example

Dim objFPC As New FPCLib.FPC
Dim objFPCArray As FPCArray
Set objFPCArray = objFPC.Arrays.CurrentArray
objFPCArray.Restore "backup file"

See Also

Using the Backup Method


Enterprise and Array Policy

Administrators can define protocol rules and site and content rules; together, these rules constitute an enterprise-level policy. The enterprise policy can be applied to any array, and can be augmented by the array's own policy. The administrator can apply and configure a global policy using the ISA administration tool or the ISA administration objects.

This section contains the following topic:

  • Add a New ISA Enterprise Policy


Add a New ISA Enterprise Policy

An ISA enterprise policy is represented by the FPCEnterprisePolicy object and the enterprise policy interfaces are accessed through the FPCEnterprise object. The FPCEnterprisePolicies.Add method adds a new ISA policy:

Dim objFPC As New FPCLib.FPC
Dim MyPolicies As FPCPolicies
Dim MyPolicy As FPCPolicy
Set MyPolicy = objFPC.EnterprisePolicies.Policies.Add("Standard Company Policy")
MyPolicy.Description = "Standard policy for all users"
'save your changes
MyPolicies.Save


Adding a Dialup Entry

When you configure routing rules or firewall chaining, you can configure the ISA Server to dial out automatically when connecting to the Internet. The ISA Server will use the specified dialup entry.

You can use this VBScript example to add a dialup entry and set credentials for the entry. Once you've created the entries, the administrator can access them through the ISA administration tool.

Sub SetPBEntries()
  Set objFPC = CreateObject("FPC.root")
  objFPC.Refresh
  Set MyArray = objFPC.Arrays.CurrentArray
  Set MyPBES = MyArray.PolicyElements.DialupEntries

  'AAA is the RAS phonebookentry name
  'AAAConnection is the ISA dialup entry.
  Set MyPBE = MyPBES.Add("AAAConnection", "AAA")
  MyPBE.AuthenticationEnabled = True
  Set MyCRD =  MyPBE.Credentials
  MyCRD.UserName = "XXX"
  MyCRD.Password = "YYY"

  MyArray.PolicyElements.DialupEntries.Save

End Sub
SetPBEntries


Scenarios

The following sections describe administrative scenarios, and how to complete the tasks involved by using the ISA administration COM objects.

  • Creating and Applying Enterprise Policy to an Array
  • Secure Web Hosting
  • Create and Update a Scheduled Content Download
  • Assign a Server Certificate from Local Computer Storage to an IP Address
  • Assign a Client Certificate to a Publishing Rule


Creating and Applying Enterprise Policy to an Array

The scenario describes the steps to take to create an enterprise policy and apply it to the enterprise or to an entire corporation. In this example, the enterprise has two branch offices, branch 1 and branch 2, each represented by an array of ISA servers.

For this example, you can assume that the corporation headquarters office policy states that employees in all branch offices are allowed HTTP access to all sites, and that the branch 1 policy allows HTTP access to members of the sales team only.

To create the enterprise policy

Follow these steps to create an enterprise policy:

  1. Create a new enterprise policy, called "HQ" (headquarters).
    'Add new policy to the enterprise policies collection
Set objPolicy = objFPC.EnterprisePolcies.Policies.Add ("HQ")
'Save Changes to the root object
objFPC.Save
  2. Add a protocol rule that allows HTTP requests to the new "HQ" policy.
    Dim objFPC As New FPCLib.FPC
Dim NewProtocolRule As FPCProtocolRule
Dim EnterprisePolicy As fpcEnterprisePolicy
' get new policy "HQ"
Set NewEnterprisePolicy = objFPC.EnterprisePolicies.Policies("HQ")
Set NewProtocolRule = NewEnterprisePolicy.ProtocolRules.Add("Branch 1 Rule")
NewProtocolRule.Save

To create an array policy for Branch 1 and implement the enterprise policy

These steps will apply the headquarters policy to Branch 1, and create a local policy to allow HTTP access to employees in the sales department only.

  1. Enable the HQ enterprise policy.
  2. Create a protocol rule that denies HTTP access to a client set that includes all users except those from the sales department.
    Dim objFPC As New FPCLib.FPC
Dim NewProtocolRule As FPCProtocolRule
Dim MyProtocols As FPCRefs
Dim MyClientSets As FPCRefs
Set NewProtocolRule = objFPC.EnterprisePolicies.Policies(1).ProtocolRules.Add("HTTP Allow")
NewProtocolRule.Action = fpcActionDeny
NewProtocolRule.ProtocolSelectionMethod = fpcSpecifiedProtocols
Set MyProtocols = NewProtocolRule.SpecifiedProtocols
MyProtocols.Add "HTTP", "", fpcEnterpriseScope
Set MyClientSets = NewProtocolRule.ClientAddressSetsUsed
MyClientSets.Add "Non Sales Team", "", fpcEnterpriseScope


Secure Web Hosting

Secure Web hosting (reverse proxying) refers to the ability of ISA Server to process incoming requests through an internal Web server, in the case of HTTP requests, or through an internal FTP server and to respond on the server's behalf. Requests are forwarded to an internal Web server, located behind the ISA server.

Web publishing rules filter all incoming and outgoing requests through the ISA server, and therefore determine how secure Web hosting functions. Web publishing rules define the mapping between incoming requests and the appropriate Web servers.

Example

This example lets you give a group of external customers access to an internal Web site, whose external domain name is www.microsoft.com/external.

To provide intranet access to external user group

  1. To fully secure your network, enable dynamic packet filtering using the FPCIpPacketFilters collection.
  2. Create a new destination set including www.microsoft.com/exteral. See Add a Destination Set.
  3. Create a new FPCWebPublishingRule that redirects external requests.
  4. Add a new FPCClientAddressSet object that defines a set including all external customers.
  5. Set the FPCWebPublishingRule.ClientAddressSetsUsed property to be the client address set that include all external customers.
  6. Set the FPCWebPublishingRule.Action property to Redirect to the internal Web server.


Create and Update a Scheduled Content Download

The following VBScript code example creates and updates a scheduled content download operation.

' script creates and updates a scheduled content download operation with
' depth = 9, TaskPeriod = fpcDownloadOnSpecifiedDaysOfWeek and
' DaysOfWeek = Everyday.
' Syntax:
' Scheduled-Content-Download-Job.vbs ArrayName URL JobName
'

'<HTML><BODY>'<script language="VBScript">
'

Function TimeToStr( iHour, iMinute )
    Dim Hour, Minute
    ' format hour
    If iHour < 10 Then
        Hour = "0" & FormatNumber(iHour,0,-1,0,-1)
    Else
        Hour = FormatNumber(iHour,0,-1,0,-1)
    End If
    If iMinute < 10 Then
        Minute = "0" & FormatNumber(iMinute,0,-1,0,-1)
    Else
        Minute = FormatNumber(iMinute,0,-1,0,-1)
    End If
    TimeToStr = Hour & ":" & Minute
End Function

Sub AddScheduledContentDownloadJob()
    Set args = Wscript.Arguments

    ' get FPC arrays object
    Set objFPC = CreateObject("FPC.Root")
    objFPC.Refresh
    Set objArrays = objFPC.Arrays

    output = ""

    ' check that we have seven arguments
    If args.Count <> 7 Then
        ' Show syntax
        output = "Invalid parameters" & vbCrLf & _
               "Syntax:" & vbCrLf & _
               "    Scheduled-Content-Download-Job.vbs <ArrayName | .> JobName URL depth limit hour minute"
    End If

    ' Get the specified ISA array
    If args.Count = 0 Then
        output = output & vbCrLf & vbCrLf & "List of arrays:" & vbCrLf
        for each objArray in objArrays
            output = output & "    " & objArray.Name & vbCrLf
        Next
    else
        ArrayName = args(0)
        If ArrayName = "." Then             ' get the local array
            Set objArray = objArrays.CurrentArray
            ArrayName = objArray.Name
        Else
            Set objArray = objArrays(ArrayName)
            If Err.Number <> 0 Then         ' specified array is not available
                Wscript.Echo "The specified array was not found"
                Exit Sub
            End If
        End If

        ' Array found
        Set DownloadContainer = objArray.Cache.ScheduledContentDownload

        If args.Count = 1 Then
            output = output & vbCrLf & vbCrLf & "List of Jobs:" & vbCrLf
            for each Job in Downloadcontainer
                output = output & "    " & Job.Name & " - " & Job.URL & "  @ " & TimeToStr( Job.SchedTimeHour, Job.SchedTimeMinute) & " (" & Job.MaxDepth & "/" & FormatNumber(Job.MaxPages,0,-1,0,-1) & ")" & vbCrLf
            Next
        else

            ' look for the job
            On Error Resume Next            ' set error handling
            set MyJob = Downloadcontainer.Item(args(1))
            If Err.Number <> 0 Then         ' Add the job
                set MyJob = Downloadcontainer.Add(args(1), args(2))
            End If
            On Error GoTo 0                 ' reset error handling

            If args.Count = 2 Then          ' 2 args display the job information
                output = output & vbCrLf & vbCrLf & "Job parameters:"

                ' get job parameters:
                output = output & vbCrLf & "    Name: " & MyJob.Name
                output = output & vbCrLf & "    URL: " & MyJob.URL
                output = output & vbCrLf & "    MaxDepth: " & MyJob.MaxDepth
                output = output & vbCrLf & "    MaxPages: " & FormatNumber(MyJob.MaxPages,0,-1,0,-1)

                ' scheduling
                output = output & vbCrLf & "    Runs at: " & MyJob.SchedTimeHour & ":" & FormatNumber(MyJob.SchedTimeMinute,0,-1,0,0)

            ' we have all the parameters, update the Job
            else
                If args.Count = 7 Then

                    If Err.Number <> 0 Then
                        Wscript.Echo "An error has occurred while creating job" & args(1) & vbCrLf & "    Error: " & Err.Description
                        Exit Sub
                    End If

                    ' set job parameters:
                    MyJob.Name = args(1)
                    MyJob.URL = args(2)
                    MyJob.Enabled  = true
                    MyJob.CacheTextOnly = false
                    MyJob.MaxDepth = args(3)
                    MyJob.MaxPages = args(4)
                    MyJob.StayInDomain = true

                    ' set scheduling
                    MyJob.SchedTimeHour = args(5)
                    MyJob.SchedTimeMinute = args(6)
                    MyJob.SetTaskPeriod 2, 127                  ' One fetch per day

                    ' set FetchUrlFlags:
                    MyJob.FetchUrlFlagForce = true
                    MyJob.FetchUrlFlagTtlOverride = false       ' use original expiration
                    MyJob.FetchUrlFlagTtlIfNone = false  ' bugbug true          ' set expiration if not available
                    MyJob.TTL = 24*60                           ' expires after 24 hours

                    ' Save
                    DownloadContainer.Save
                    If Err.Number <> 0 Then
                        Wscript.Echo "An error has occurred:" & vbCrLf & Err.Description
                    Else
                        Wscript.Echo "Scheduled content download job successfully created/updated"
                    End If
                    Exit Sub        ' out we go
                End If
            End If
        End If
    End If

    ' display message
    Wscript.Echo output

End Sub

AddScheduledContentDownloadJob

'</script></BODY></HTML>


Assign a Server Certificate from Local Computer Storage to an IP Address

The following VBScript example assigns an SSL server certificate from the local computer storage to an IP address by using the FPCServer object. After you run this script, the IP address on the computer where the certificate is stored will use the certificate for incoming Web requests.

call Install

Sub Install

        Set fpc = CreateObject("FPC.Root")
        Set CurServer = fpc.Arrays(1).Servers(1)
        NL = Chr(13) & Chr(10)
        TAB = Chr(9)
        Set certs = CurServer.SSLServerCertificates
        Dim i
        i = 1
        Dim certificates
        certificates = ""
        For Each cert In certs
            certificates = certificates & _
            i & ":" & NL & _
                "Friendly Name:" & TAB & cert.FriendlyName &   NL & _
            "Issued To:"     & TAB & cert.IssuedTo &       NL & _
                "Issued By:"     & TAB & cert.IssuedBy &       NL & _
                    "Expires at:"    & TAB & cert.ExpirationDate & NL
            i = i + 1
        Next

        Dim n
        n = InputBox(certificates & "Which certificate do you choose?", "Choose A Server Certificate")
        n = CInt(n)
        if not n > 0 and n < i then
                MsgBox "You chose a wrong number (" & n & ")" & NL & _
                       "Choose a number between 1 and " & i - 1
                Exit Sub
        end if

        Set cert = CurServer.SSLServerCertificates(n)

        MsgBox "You chose " & n & ":" & NL & _
               "Friendly Name:" & TAB & cert.FriendlyName & NL &_
               "Issued To:"     & TAB & cert.IssuedTo & NL & _
               "Issued By:"     & TAB & cert.IssuedBy & NL & _
               "Expires at:"    & TAB & cert.ExpirationDate

        CurServer.ReverseProxyListen.AllSSLServerCertificate = cert
        CurServer.ReverseProxyListen.Save
        MsgBox "done"
End Sub


Assign a Client Certificate to a Publishing Rule

The following VBScript code example assigns a client certificate to a publishing rule.

Example

call Install

Sub Install
        Set fpc = CreateObject("FPC.Root")
        Set CurServer = fpc.Arrays(1).Servers(1)
        NL = Chr(13) & Chr(10)
        TAB = Chr(9)
        Set certs = CurServer.SSLClientCertificates
        Dim i
        i = 1
        Dim certificates
        certificates = ""
        For Each cert In certs
            certificates = certificates & _
                i & ":" & TAB & cert.FriendlyName & NL & _
                          TAB & cert.IssuedTo & NL & _
                          TAB & cert.IssuedBy & NL & _
                          TAB & cert.ExpirationDate & NL & NL
            i = i + 1
        Next

        Dim n

        n = InputBox(certificates & "Which certificate do you choose?", "Choose A Client Certificate")

        if not n > 0 and n < i then
                MsgBox "You chose a wrong number (" & n & ")" & NL & _
                       "Choose a number between 1 and " & i - 1
                Exit Sub
        end if

        Set cert = CurServer.SSLClientCertificates(n)

        MsgBox "You chose " & n & ":" & NL & _
               "Friendly Name:" & TAB & cert.FriendlyName & NL &_
               "Issued To:"     & TAB & cert.IssuedTo & NL & _
               "Issued By:"     & TAB & cert.IssuedBy & NL & _
               "Expires at:"    & TAB & cert.ExpirationDate

        Set rules = fpc.Arrays(1).Publishing.WebPublishingRules

        i = 1
        Dim PubRules
        PubRules = ""
        For each rule in rules
            PubRules = PubRules & _
                i & ":" & TAB & rule.Name & NL & NL
            i = i + 1
        Next

        n = InputBox(PubRules & "Which publish rule do you choose?", "Choose a publish rule")
        if not n > 0 and n < i - 2 then
                MsgBox "You chose a wrong number (" & n & ")" & NL & _
                       "Choose a number between 1 and " & i - 2
                Exit Sub
        end if

        Set rule = fpc.Arrays(1).Publishing.WebPublishingRules(CInt(n))

        MsgBox "You chose " & m & ":" & NL & _
               "Name:" & TAB & rule.Name

        rule.SSLClientCertificate = cert
        rule.Save

        MsgBox "done"

End sub


Script Samples

The ISA Server SDK provides example code to demonstrate ISA's scripting capabilities. Sample administration scripts are provided on the CD-ROM in the folder SDK\samples\admin\scripts.

The scripts provided on the CD are:

  • Add_Dod
  • AddLATEntry
  • AddScheduledContentDownload
  • CacheSettings
  • ConstructLAT
  • DisableScheduledContentDownloads
  • Enterprise_Destination
  • FetchUrl
  • ListServers
  • ApplicationFilterList
  • FindScheduledContentDownload
  • SetCache
  • Remove_Unused_DialUpEntries
  • SetUpstreamRouting
  • ShowAllProtocolRules
  • ShowAllRoutingRules
  • StaticFilter


Add_Dod

Add_Dod is a VBScript sample that demonstrates how to add a new Dialup Entry and set the Dialup Entry Credentials. The script also sets one Routing rule to use the new Dialup Entry.


AddLATEntry

AddLATEntry is a VBScript sample that demonstrates how to add an IP range to a Local Address Table (LAT). This sample accesses the FPCLAT collection, which represents the LAT, and then adds an entry to the table through the FPCLAT.Add method.


AddScheduledContentDownload

AddScheduledContentDownload is a VBScript sample that receives an array name, a URL, and a job name, and adds a prefetcher job with depth = 3, TaskPeriod = PrefetcherSpecifiedDaysOfWeek and DaysOfWeek = Sunday and Tuesday.


CacheSettings

CacheSettings is a VBScript sample that prompts the user to enter the name of an array, then displays the cache settings of that array. The settings include whether active caching is enabled, the cache drives present in the array, and the total size of the cache. The listing of available drives and their sizes are obtained through properties of the FPCCacheDrives collection. You can obtain information regarding active caching status through the FPCCacheConfiguration object. Both VBScript and JavaScript samples are provided.


ConstructLAT

ConstructLAT is a VBScript sample that demonstrates how to construct the Local Address Table (LAT) of an array based on its network interface cards (NICs). The script goes through each NIC and asks the user whether it should be included in the LAT. The LAT is built based on user responses. Both VBScript and JavaScript samples are provided.


DisableScheduledContentDownloads

DisableScheduledContentDownloads is a VBScript sample that disables all prefetcher jobs on Monday and Wednesday in a given array.


Enterprise_Destination

The Enterprise_Destination sample is a VBScript that will adds a new Destination Set to the Enterprise, sets the array policy to use Array and Enterprise Policies, and configures the new rule to use the Enterprise Destination.

Only an enterprise administrator can run this script.


FetchUrl

FetchUrl is a VBScript sample that causes the Web proxy service to fetch an object and store it in the Web proxy service's cache. The Web proxy service can store the cached object under a different name than that of the source object. This script also allows you to specify how long the object should be considered "fresh" within the cache. This is done by setting the cached object's Time-to-Live (TTL) property.


ListServers

ListServers is a VBScript sample that lists all the servers in a given array through the Name property of the FPCArray object. Both VBScript and JavaScript samples are provided.


ApplicationFilterList

ApplicationFilterList is a VBScript sample that prompts the user to enter an array and then lists the plug-ins of the selected array. The plug-in's name, version, and vendor are listed through use of the FPCApplicationFilters collection. Both VBScript and JScript samples are provided on the CD.


FindScheduledContentDownload

FindScheduledContentDownload is a VBscript sample that receives an array name and a URL and checks whether any job includes that URL.


Remove_Unused_DialUpEntries

Remove_Unused_DialUpEntries is a VBScript sample that removes from the DialUpEntries list all of the DialUpEntries that are not in use at themoment that the script runs.


SetCache

SetCache is a VBScript sample that configures cache settings. The script tells the user whether caching is enabled or disabled, and allows that setting to be changed. The script then indicates whether active caching is enabled or disabled, and allows that setting to be changed. You can access the caching and active caching settings through the FPCCacheConfiguration object.


SetUpstreamRouting

SetUpstreamRouting is a VBScript sample that demonstrates how to set up upstream routing to another server by using the FPCRoutingRules collection and the FPCPrimaryRoute object. This script is based on command line arguments, and illustrates how to change routing rules with the FPCRoutingRule object.


ShowAllProtocolRules

ShowAllProtocolRules is a VBScript sample that lists all the protocol rules of an array by looping through the FPCProtocolRules collection. Both VBScript and JavaScript samples are provided.


ShowAllRoutingRules

ShowAllRoutingRules is a VBScript sample that lists all the routing rules of an array by looping through the FPCRoutingRules collection. The script also lists whether or not each routing rule is enabled or disabled, and the action that the rule follows.


StaticFilter

StaticFilter is a VBScript sample that demonstrates how to add a static IP packet filter that allows Network Time Protocol (NTP) communication from the ISA Server computer to the Internet. NTP uses port 123, UDP protocol.


Extending the ISA Administration Tool

The Internet Security and Acceleration (ISA) Server 2000 administration tool is designed to be extensible. One way that you can extend the administration tool is to use Microsoft® Management Console (MMC) extension snap-ins. The topic How to Create a Microsoft Management Console Snap-in provides general information on how to create an MMC snap-in for ISA, and an example MMC snap-in for an ISA application filter.

Any ISA node can be extended with a snap-in.

What Can Extension Snap-ins Extend?

Extension snap-ins can extend the following:

  • The name space by adding scope pane child nodes.
  • Context menus.
  • Toolbars and toolbar buttons.
  • Property pages.

For more information please refer to the MMC documentation.

There are several steps you need to take to create an extension snap-in.

To create an extension snap-in

  1. Define your schema in the FPCVendorParametersSet object.
  2. Write the code for the MMC snap-in.
  3. Store/retrieve the data in FPCVendorParametersSet though the FPCSnapinNode.CurrentObject property.

Each node of an ISA snap-in exposes its specific data to extension snap-ins using the COM interface: IFPCSnapinNode. The interface contains four properties:

  • ParentArray (of type IDispatch)
  • CurrentObject (of type IDispatch)
  • ComRoot (of type IDispatch)
  • ParentPolicy (of type IDispatch)

The IFPCSnapinNode can be retrieved by querying the IDataObject interface of the ISA node that you want to extend. The ParentArray property is an FPCArray object as exposed through the ISA administration COM object model. Note that this property returns an error for the Root node of the ISA snap-in. The CurrentObject property is interface-specific to the node to be extended. See How to Create a Microsoft Management Console Snap-in for more details.

The ISA nodes that support MMC extensions and their GUIDs are listed in the Globally Unique Identifiers section of Reference.


How to Create a Microsoft Management Console Snap-in

This section explains how to create property sheets. In describing the procedures and code needed to create the Microsoft Management Console (MMC) snap-in, this document uses the example of the Simple Mail Transfer Protocol (SMTP) filter created in How to Create an Application Filter.

You can use ISA Server to create application filters. After creating the application filters, you can use the Microsoft Management Console (MMC), described in MSDN, to modify the application filter properties in the ISA administration tool.

This section contains the following topic:

  • Creating a Microsoft Management Console Snap-in for an Application Filter


Creating a Microsoft Management Console Snap-in for an Application Filter

To create a Microsoft Management Console (MMC) snap-in for an application filter you need to follow these steps, as described in the following sections:

  1. Create the property sheet. Initially, this property sheet will be displayed for all of the application filters.
  2. Test the property sheet extension.
  3. Limit the property sheet, so that it displays only on the relevant application filter.
  4. Design the property page layout.
  5. Create message handlers for the property sheet elements.
  6. Load filter configuration data from vendor parameter sets and display it in the administration tool.
  7. Save the configuration data from the administration tool to the vendor parameter set.


Creating the Property Sheet

Follow the procedure in this section to create the property sheet. This must be done on a computer that has the ISA administration tool installed.

To create the property sheet

  1. In Microsoft Visual C++® 6.0, on the File menu, click New.
  2. On the Projects tab, click ATL Com App Wizard.
  3. In the Project Name box, type SMTPFilterConfig.
  4. Click Finish.
  5. On the Insert menu, click New ATL Object…
  6. In the Objects list view, select MMC Snap-in.
  7. Click Next.
  8. On the Names tab, type SmtpFltrSnapIn in the ShortName box.
  9. On the MMC Snapin tab, select the Extension and IExtendPropertySheet check boxes. (Be sure to leave checked the following check boxes: IComponentData, IComponent, and ISnapInAbout).
  10. Clear the Support Persistence check box.
  11. On the MMC Snapin tab, in the Extends Node box, select ISA Application Filter.

    Warning Be sure not to select ISA Application Filters.

  12. Edit SmtpFltrSnapIn.cpp:

    Comment out the line

    if (type == CCT_SCOPE || type == CCT_RESULT)

    that is shown as a comment in the following code:

    HRESULT CSmtpFltrSnapInExtData::CreatePropertyPages(LPPROPERTYSHEETCALLBACK lpProvider,
    long handle,
    IUnknown* pUnk,
    DATA_OBJECT_TYPES type)
{
    // if (type == CCT_SCOPE || type == CCT_RESULT)
    {
        CSmtpFltrSnapInPage* pPage = new CSmtpFltrSnapInPage(handle, true, _T("SmtpFltrSnapIn"));
        lpProvider->AddPage(pPage->Create());
        // The second parameter to the property page class constructor
        // should be true for only one page.

        // TODO : Add code here to add additional pages
        return S_OK;
    }
    return E_UNEXPECTED;
}
  13. In SmtpFltrSnapIn.h, in the CSmtpFltrSnapInExtData class, comment out the line shown as a comment in the following code:
        STDMETHOD(QueryPagesFor)(DATA_OBJECT_TYPES type)
    {
        // if (type == CCT_SCOPE || type == CCT_RESULT)
            return S_OK;
        return S_FALSE;
    }
  14. Build.


Testing the Property Sheet Extension

Follow this procedure to test the new property sheet.

To test the new property sheet

  1. Run the ISA administration tool (Click Start, point to Programs, point to Microsoft ISA Server, and then click ISA Administration Tool).
  2. Select the applicable domain array, select Extensions and then click Application Filters.
  3. Select any of the application filters listed in the details pane. Note that each of the application filters has a new property sheet called SmtpFltrSnapIn (and it is empty).


Limiting the Property Sheet Display

The property sheet should display only on the relevant application filter; in this case, on the SMTP application filter.

To limit the property sheet display

  1. Select a unique attribute for the application filter; for example, its GUID.
  2. Copy the file msfpccom.dll to your project directory. This file is located on the ISA Server compact disc, in the i386 directory.
  3. In SmtpFltrSnapIn.h add the following #import statement:
    #import "msfpccom.dll"

    The #import directive is used to incorporate information from a type library. The content of the type library is converted into C++ classes, mostly describing the COM interfaces.

  4. In SmtpFilterSnapIn.cpp, add the code that is in bold font in the following sample to this method:
    HRESULT CSMTPFilterSnapInExtData::CreatePropertyPages(LPPROPERTYSHEETCALLBACK lpProvider,
    long handle,
    IUnknown* pUnk,
    DATA_OBJECT_TYPES type)
{
    FPCLib::IFPCSnapinNodePtr spiFPCSnapinNode(m_pDataObject);

    FPCLib::IFPCFirewallFilterPtr spiFPCFirewallFilter(spiFPCSnapinNode->CurrentObject);

    _bstr_t bstrGUID(spiFirewallFilter->GetGuid());

    // if (type == CCT_SCOPE || type == CCT_RESULT)
    if (bstrGUID == _bstr_t("{179A0A70-1EF5-11D3-B160-00A0C9E3F998}"))  // Smtp Filter GUID
    {
CSMTPFilterSnapInPage* pPage =
new CSMTPFilterSnapInPage (handle, true, _T("SMTPFilterSnapIn"));
        lpProvider->AddPage(pPage->Create());
        // The second parameter to the property page class constructor
        // should be true for only one page.

        // TODO : Add code here to add additional pages
        return S_OK;
    }
    return E_UNEXPECTED;
}
  5. Build.
  6. Test. Run the ISA administration tool. Notice that the property sheet appears only on the SMTP application filter.


Designing the Property Page Layout

Once you've succeeded in testing the property page, you can change its design.

To design the property page

  1. In Visual C++ 6.0, click the Resource View tab.
  2. Double-click the IDD_SmtpFilterSnapIn node in the Dialog section.

3. Use the Controls floating menu to select the graphical elements to place on the page.


Creating Message Handlers for the Property Sheet Elements

You need to add handlers to the design elements you placed on the property page.

To create the message handlers

1. Double-click a design element on the property page.

  2. Select the design element name from the Class or object to handle list.
  3. Select the name of the event you want to handle (for example, the EN_CHANGE event).
  4. Click the Add and Edit button – this will generate the needed method specification and let you edit the code. For example, if you use the EN_CHANGE event in the IDC_VIRUS_STRING edit box, the following code will be generated:
    LRESULT OnChange_VirusString(WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL& bHandled)
    {
        // TODO : Add Code for control notification handler.
        return 0;
    }
  5. You would like, at least, to enable the Apply button whenever a change to any of the controls is made. To do so you need to add the following code to the message handler:
        // Enable the Apply button
    SetModified();


Loading and Displaying the Filter Configuration

Note that the fields on the property page you will create are based on information extracted from FPCApplicationFilter.VendorParametersSets. The FPCFirewallFilter object is identified by the filter GUID, and is created when a user accesses the filter node in the ISA MMC snap-in. When the property page is created, it runs on a separate thread from that of the FPCFirewallFilter object. For this reason, part of the code provided in this example uses marshalling techniques so that pointers can be passed between these two threads.

To load and display the filter configuration

  1. In order to read the values stored in the filter vendor parameter set, add the following function to your project:
    HRESULT GetVendorData(FPCLib::IFirewallFilterPtr spiFirewallFilter,
                _bstr_t* pbsVirusString,
                _bstr_t* pbsPrefixString,
                _bstr_t* pbsSMTPIPAddress)
{
    HRESULT hr = S_OK;
    FPCLib::IFPCVendorParametersSetsPtr spIFPCVendorParametersSets;
    FPCLib::IFPCVendorParametersSetPtr spIFPCVendorParametersSet;

    try
    {
        spIFPCVendorParametersSet = spiFilterFirewall->VendorParametersSets->Item(_bstr_t(PARAM_SET_GUID));
        *pbsVirusString  = spIFPCVendorParametersSet->Value[_bstr_t("VirusString")];
        *pbsPrefixString = spIFPCVendorParametersSet->Value[_bstr_t("PrefixString")];
        *pbsSMTPIPAddress = spIFPCVendorParametersSet->Value[_bstr_t("SMTPIPAddress")];
    }
    catch(_com_error& err)
    {
        return err.Error();
    }

    return S_OK;
}
  2. You need to add code that will call GetVendorData() and display the received data on the property page. Create the OnInitDialog method, using the message-handler wizard. Do this in the same way that you create other message handlers: Use the dialog itself as the control in the Class or object to handle list and the WM_INITDIALOG message as the event. Add the following code to the generated code (the m_hWnd serves as a handle to the property page; use it when you need to access any of the controls on the property page):
            HRESULT hr;

        _bstr_t bsVirusString, bsPrefixString;
    // Unmarshall an object interface pointer.
    hr =  CoGetInterfaceAndReleaseStream(
                    m_spStreamMarshalFirewallFilter,
                    FPCLib::IID_IFirewallFilter,
                    (void**)&m_spiFirewallFilter);

    // CoGetInterfaceAndReleaseStream releases m_spStreamMarshalFirewallFilter even if it fails.
    // We set it to NULL so that the destructor doesn't try to release this again.
    m_spStreamMarshalFirewallFilter.p = NULL;

    if (FAILED(hr) || !m_spiFirewallFilter.operator bool())
        return hr;

        hr = ::GetVendorData (m_spiFirewallFilter, &bsVirusString, &bsPrefixString);
        if (FAILED (hr))
        {
            bsVirusString  = "Default Virus String";
            bsPrefixString = "Default Prefix String";
        }

        ::SetWindowText (::GetDlgItem (m_hWnd, IDC_VIRUS_STRING),  bsVirusString);
        ::SetWindowText (::GetDlgItem (m_hWnd, IDC_PREFIX_STRING), bsPrefixString);
  3. Add initialization method for the class SmtpFltrSnapInPage:
    //This method is used for passing a pointer to the FirewallFilter object of the SMTP filter
    HRESULT Initialize(FPCLib::IFirewallFilterPtr DataSource)
    {
        HRESULT hr=S_OK;

        hr = CoMarshalInterThreadInterfaceInStream(FPCLib::IID_IFirewallFilter,
                    (IUnknown *)DataSource,
                    &m_spStreamMarshalFirewallFilter);

        return hr;
    }

    and add the two following private members for the class:

    private:
    FPCLib::IFirewallFilterPtr m_spiFirewallFilter;
        // Pointer to stream into which this page's IFirewallFilter object interface
        // pointer will be marshaled.
        CComPtr<IStream>    m_spStreamMarshalFirewallFilter;
  4. Check whether the page was created and initialize the page.
  5. Add the code that is shown in bold font to SmtpFltrSnapIn.cpp.
    HRESULT CSmtpFltrSnapInExtData::CreatePropertyPages(LPPROPERTYSHEETCALLBACK lpProvider,
    long handle,
    IUnknown* pUnk,
    DATA_OBJECT_TYPES type)
{
HRESULT hr;
    // if (type == CCT_SCOPE || type == CCT_RESULT)
    {
        CSmtpFltrSnapInPage* pPage = new CSmtpFltrSnapInPage(handle, true, _T("SmtpFltrSnapIn"));
        //Check whether the page was created
        if(pPage == NULL)
            return E_UNEXPECTED;
        //Initialize the page.
        if (FAILED(hr=pPage->Initialize(spiFirewallFilter)))
            return hr;
        lpProvider->AddPage(pPage->Create());
        // The second parameter to the property page class constructor
        // should be true for only one page.

        // TODO : Add code here to add additional pages
        return S_OK;
    }
    return E_UNEXPECTED;
}


Saving Configuration Data in the Vendor Parameter Set

Using this procedure, add code to save the filter configuration data in the vendor parameter set.

To save the filter configuration data in the vendor parameter set

  1. Add the following function to store the values in the filter's vendor parameter set:
    HRESULT PutVendorData(FPCLib::IFirewallFilterPtr spiFirewallFilter,
                    const _bstr_t& bsVirusString,
                    const _bstr_t& bsPrefixString,
                    const _bstr_t& bsSMTPIPAddress)
{
    HRESULT hr = S_OK;
    FPCLib::IFPCVendorParametersSetsPtr spIFPCVendorParametersSets;
    FPCLib::IFPCVendorParametersSetPtr spIFPCVendorParametersSet;

    try
    {
        spIFPCVendorParametersSets = spiFirewallFilter->VendorParametersSets;

        try
        {
            spIFPCVendorParametersSet = spIFPCVendorParametersSets->Item(_bstr_t(PARAM_SET_GUID));
        }
        catch(_com_error&)
        {
            //Create a new parameter set
            spIFPCVendorParametersSet = spIFPCVendorParametersSets->Add(_bstr_t(PARAM_SET_GUID),VARIANT_FALSE);

            spIFPCVendorParametersSets->Save(FALSE);
        }

        spIFPCVendorParametersSet->Value[_bstr_t("VirusString")]   = bsVirusString;
        spIFPCVendorParametersSet->Value[_bstr_t("PrefixString")]  = bsPrefixString;
        spIFPCVendorParametersSet->Value[_bstr_t("SMTPIPAddress")] = bsSMTPIPAddress;
        spIFPCVendorParametersSet->Save(FALSE);

    }
    catch(_com_error& err)
    {
        return err.Error();
    }

    return S_OK;
}
  2. You need to add a function that will call PutVendorData with the values from the ISA administration tool. To implement this function, override the OnApply method of the CSnapInPropertyPageImpl class. This method is called whenever you click the Apply or OK buttons. Add the following code to your class:
        // This member function is called when the user clicks the OK or the Apply button.
    virtual BOOL OnApply()
    {
        HRESULT hr;
        // _bstr_t bsVirusString, bsPrefixString;
        char sVirusString[100], sPrefixString[100];

        ::GetWindowTextA (::GetDlgItem (m_hWnd, IDC_VIRUS_STRING),
                            reinterpret_cast <char *> (&sVirusString),
                            100);

        ::GetWindowTextA (::GetDlgItem (m_hWnd, IDC_PREFIX_STRING),
                             reinterpret_cast <char *> (&sPrefixString),
                            100);

        hr = ::PutVendorData (m_spiFirewallFilter,
                    _bstr_t(sVirusString),
                    _bstr_t(sPrefixString));

        return TRUE;
    }
  3. Build.


How to Create a Context-Sensitive Menu Extension

The ISA Software Developer's Kit (SDK) includes a sample that extends the ISA administration tool by adding a context sensitive menu. The sample files are in the serversconfigsample directory, under the samples directory in the SDK. The sample adds a menu to the servers node in the administration tool, and by clicking on the node you can see all the adapters for each server in the domain array.

This section contains the following topics:

  • Building the Context-Sensitive Menu Sample
  • Context-Sensitive Menu Sample Steps
  • Remote Administration Installation


Building the Context-Sensitive Menu Sample

The sample is included in the samples folder of the SDK, in the folder serversconfigsample. To build the sample take the following steps.

To build the context-sensitive menu included in the SDK

  1. Open Microsoft Visual Studio®.
  2. Open the sample workspace, serversconfigsample.dsw.
  3. To see the project files, select the View menu, and then the workspace.
  4. Press the F7 key to build the sample.

This will create the necessary dynamic-link library (DLL). When you register this DLL, you can see the menu when you right click on the servers node in the ISA administration tool and select "view adapters".


Context-Sensitive Menu Sample Steps

To show the context sensitive menu, the sample traverses all the servers in the domain array, retrieving all the adapters. The information about the adapters on each server is obtained through the administration COM objects. This sample retrieves in formation about the servers in the domain array through the IFPCServers and IFPCServer interfaces, and information about the adapters is retrieved through the IFPCAdapter and IFPCAdapterList interfaces.

The sample takes the following steps:

  1. Retrieves each server in the array.
  2. Lists all the adapters on each server.
  3. Displays all the adapters.


Retrieving Each Server in the Array

The following code retrieves and stores each server and adapter. This code is taken from the file AdapterList.cpp, included in the serversconfigsample directory.

  1. Create the tree that stores the server and adapter information, shown here:
        /* Make the root of the tree */
    HTREEITEM RootItem = m_ListTree.InsertItem( _T("All Servers"), 0, 0);
    HTREEITEM ServItem;

    /* Make headlines */
    m_ListCtl.InsertColumn( 0, _T("Server Name") );
    m_ListCtl.InsertColumn( 1, _T("Adapter Description") );

    m_ListCtl.SetColumnWidth( 0, LVSCW_AUTOSIZE_USEHEADER );
    m_ListCtl.SetColumnWidth( 1, LVSCW_AUTOSIZE_USEHEADER);
  2. Find each server in the array, shown here:
        /* Go along the hierarchy to find the all the servers */
    /* and their adapters                                 */
    FPCLib::IFPCSnapinNodePtr spiFPCSnapinNode(m_pDataObject);
    FPCLib::IFPCServersPtr spiServers(spiFPCSnapinNode->CurrentObject);


Listing the Adapters

Now that each server has been retrieved, the names of each adapter must be retrieved. This code is taken from the file AdapterList.cpp, included in the serversconfigsample directory.

The code will loop through all the servers in the array, then find all adapters on each server. The names of each are stored, shown below. Each adapter stored in this list will be displayed in the menu.

  1. Find the number of servers in the array. Here the number of servers is being retrieved using the Count property of the FPCServer administration COM object.
        int Servnum = spiServers->Count;
    int index,index2,LineNumber=0;
    VARIANT ItemNum;
  2. Loop through all servers in the array, and find all adapters on each server. Here is where the code uses the administration objects AdapterList and FPCServer to retrieve information about the adapters.
        /* Loop on all the servers */
    for (index=1;index<=Servnum;index++)
    {
        ItemNum.vt = VT_I4;
        ItemNum.lVal =  index;
        FPCLib::IFPCServerPtr spiServer(spiServers->Item(ItemNum));
        _bstr_t name = spiServer->Name;
        FPCLib::IAdapterListPtr spiAdapterList(spiServer->AdapterList);

        int AdapNum = spiAdapterList->Count;

        /* Make a node for this server */
        ServItem = m_ListTree.InsertItem( name, 0, 0,RootItem);

        /* Loop on all the adapters */
        for (index2=1;index2<=AdapNum;index2++)
        {
            ItemNum.vt = VT_I4;
            ItemNum.lVal =  index2;
            FPCLib::IAdapterPtr spiAdapter(spiAdapterList->Item(ItemNum));
            _bstr_t Desc = spiAdapter->Description;

            /* Make a line for every adapter */
            m_ListTree.InsertItem( Desc, 0, 0,ServItem);
            m_ListCtl.InsertItem( (LineNumber), _T(""));
            m_ListCtl.SetItemText((LineNumber),0, name );
            m_ListCtl.SetItemText((LineNumber),1, Desc);
            LineNumber++;

        }

    }


Displaying the Adapters

The code below works with the MMC console to show the adapters. This code is taken from the file Adapters.cpp, in the sample directory, and is written by the Active Template Library (ATL) object wizard, used at the start of development.

To use the ATL object wizard

  1. Open Microsoft Visual C++.
  2. Click New ATL Object on the Insert menu.
  3. Select MMC Snapin from the Objects list.
  4. Click Next.
  5. Type Adapters in the ShortName box on the Names tab.
  6. Select the Extension and IExtendcontextmenu check boxes on the MMC Snapin tab. (Be sure to leave IComponentData, IComponent, and ISnapInAbout checked.).
  7. Clear the Support Persistence check box.
  8. On the MMC Snapin tab, in the Extends Node box, select the node you want to extend(servers).

The wizard produces the following code.

HRESULT CAdaptersData::Notify( MMC_NOTIFY_TYPE event,
    long arg,
    long param,
    IComponentData* pComponentData,
    IComponent* pComponent,
    DATA_OBJECT_TYPES type)
{
    // Add code to handle the different notifications.
    // Handle MMCN_SHOW and MMCN_EXPAND to enumerate child items.
    // In response to MMCN_SHOW you must enumerate both the scope
    // and result-pane items.
    // For MMCN_EXPAND you only need to enumerate the scope items
    // Use IConsoleNameSpace::InsertItem to insert scope pane items
    // Use IResultData::InsertItem to insert result pane item.
    HRESULT hr = E_NOTIMPL;

    _ASSERTE(pComponentData != NULL || pComponent != NULL);

    CComPtr<IConsole> spConsole;
    CComQIPtr<IHeaderCtrl, &IID_IHeaderCtrl> spHeader;
    if (pComponentData != NULL)
        spConsole = ((CAdapters*)pComponentData)->m_spConsole;
    else
    {
        spConsole = ((CAdaptersComponent*)pComponent)->m_spConsole;
        spHeader = spConsole;
    }

    switch (event)
    {
    case MMCN_SHOW:
        {
            CComQIPtr<IResultData, &IID_IResultData> spResultData(spConsole);
            // TODO : Enumerate the result pane items
            hr = S_OK;
            break;
        }
    case MMCN_EXPAND:
        {
            CComQIPtr<IConsoleNameSpace, &IID_IConsoleNameSpace> spConsoleNameSpace(spConsole);
            // TODO : Enumerate scope pane items
            hr = S_OK;
            break;
        }
    case MMCN_ADD_IMAGES:
        {
            // Add Images
            IImageList* pImageList = (IImageList*) arg;
            hr = E_FAIL;
            // Load bitmaps associated with the scope pane
            // and add them to the image list
            // Loads the default bitmaps generated by the wizard
            // Change as required
            HBITMAP hBitmap16 = LoadBitmap(_Module.GetResourceInstance(), MAKEINTRESOURCE(IDB_ADAPTERS_16));
            if (hBitmap16 != NULL)
            {
                HBITMAP hBitmap32 = LoadBitmap(_Module.GetResourceInstance(), MAKEINTRESOURCE(IDB_ADAPTERS_32));
                if (hBitmap32 != NULL)
                {
                    hr = pImageList->ImageListSetStrip((long*)hBitmap16,
                    (long*)hBitmap32, 0, RGB(0, 128, 128));
                    if (FAILED(hr))
                        ATLTRACE(_T("IImageList::ImageListSetStrip failed\n"));
                }
            }
            break;
        }
    }
    return hr;
}


Remote Administration Installation

A user may choose to install only the administration components of ISA Server on a particular computer, thereby creating a remote administration computer for ISA Server. That computer will provide the administrator with the ISA Server administration tool, but will not include ISA engine components

If your filter includes user interface elements, you should provide an administration component installation option. The administrator will then be able to install only the administrator's user interface for your filter to the administration computer, and install the filter itself to ISA Server computers.


Developing Application Filters

This section describes the basic steps required to create an application filter. This section is intended for developers who are familiar with Microsoft® Visual C++® and COM. Because application filters work with the Firewall service, and the Firewall service works with Windows Sockets (Winsock), knowledge of Winsock is also helpful. Information about Winsock can be found in MSDN.

To become familiar with the filter development process, the following approach is recommended:

  1. Read the description of Internet Security and Acceleration (ISA) architecture in About Internet Security and Acceleration.
  2. Read Introducing Application Filters for information on the basics of filter functionality.
  3. Study Filter Development Tools, particularly the general descriptions of the basic and advanced object interfaces needed for filter creation.
  4. Work through the step-by-step procedure provided in How to Create an Application Filter.
  5. Examine the logic and interface usage of the sample filters provided with ISA.
  6. Develop a simple filter. See the Reference for details on interface methods and parameters.

Topics in this Section

This section contains the following topics:

  • Introducing Application Filters
  • Filter Development
  • Application Filter Test Environment
  • Filter Setup
  • How to Create an Application Filter
  • Sample Filters


Introducing Application Filters

Application filters work with the Firewall service to intercept and process data. Application filters can access the data stream or datagrams associated with a session within the Firewall service. The filters are registered with the Firewall service and act according to events detected by the service. An application filter can perform protocol-specific or system-specific tasks, such as authentication and checking for viruses.

This section contains the following topics, which are best read in sequence:

  1. Filter Types
  2. Proxy Events
  3. Connection Emulation
  4. Checking Access Rights
  5. Asynchronous Input/Output
  6. Filter Requirements for SecureNAT Clients
  7. Filter Requirements for Firewall Clients
  8. Setting Filter Priorities
  9. Application Filter Objects
  10. Filter Object Model


Filter Types

You can develop a wide range of application filters using the ISA Software Developer's Kit (SDK). Examples of filter types are:

  1. Protocol-enabling filters: These filters enable the usage of a protocol through the Firewall service. These filters open dynamic secondary ports, and edit Secure Network Address Translation (SecureNAT) addresses. The FTP and H.323 filters provided with ISA Server are examples of protocol-enabling filters.
  2. Protocol-scanning filters: These filter scan data from specific protocols for intrusion, viruses etc. Examples of protocol-scanning filters are the Internet Security Systems (ISS) POP and DNS filters that are provided with ISA Server.
  3. Redirection filters: These filters may cause specific connections to be redirected into their control, and act as a server. For example: The HTTP filter provided with ISA Server redirects HTTP connections to the w3proxy service.
  4. Other filters, such as those that check content. ISA Server's architecture allows developers a great deal of latitude in creating filters.


Proxy Events

Proxy events are events that the Firewall service detects. An application filter has to be registered for specific events. If that event is detected by the Firewall service, the filter is attached to the related session. The filter can then monitor the session for events where a filter response, such as data filtering, might be needed.

In general, the events are generated both in the case of Firewall clients and SecureNAT clients. For more information and a list of events, see FwxProxyEventType.


Connection Emulation

You can design a filter that intercepts a client request to connect to the Internet, and instead provide the information from another source. In this case, you are emulating an outside connection, and the client will be unaware that the data is coming from a source other than the requested external one. An HTTP filter that provides a Web object from a cache is emulating a connection.

An inbound connection can also be emulated. For example, a filter can emulate a connection on a single well-known port, so that a number of client machines can effectively use the connection simultaneously. This emulation scenario is demonstrated in the ServerSplit sample.


Checking Access Rights

When a client requests an external connection, the Firewall service determines if the client is allowed to access the connection. The Firewall service checks:

  • Which protocol the connection will use.
  • Whether the client has the right to make a connection using that protocol.

The Firewall service can determine which protocol the connection will use, based on a protocol schema it can reference. This schema, provided to the Firewall service as a feature of ISA, recognizes a defined set of protocols. The Firewall service also uses the protocol-recognition capabilities of application filters in the identification process. The advantage of filter control of protocol recognition is that a filter can recognize which protocol is associated with a secondary connection, whereas the Firewall service cannot.

The Firewall service takes two sequential steps to determine whether a client is allowed access to the connection. If the connection is denied at any point in the process, the service stops the checking procedure and denies the connection. The two steps are:

  1. Checking site and content rules.
  2. Checking protocol rules. Checking protocol rules takes place in three sequential phases:
    1. Checking against the protocol schema.
    2. Checking whether the IFWXSession::AllowFutureConnect method has been set.
    3. Checking whether the IFWXConnection::SetProtocol method is called by a filter.

Checking Site and Content Rules

When the Firewall service checks site and content rules, the connection will be denied if the rules do not permit the client to connect to that destination. If the rules allow the client to make that connection, or if the service does not recognize the protocol, the service passes along the request to the second step — checking protocol rules. At this point, the permission is "unset", because the service is not authorized to allow the connection based solely on the site and content rules.

For more information about site and content rules, see the FPCSiteAndContentRule object or the ISA product documentation.

Checking Protocol Rules

After checking the site and content rules, the Firewall service checks the protocol rules configured by the administrator. These rules allow or deny connection requests based on the protocol. If allowed, the connection request is passed to the registered filters for their review.

When the Firewall service checks protocol rules it starts by referring to the protocol schema in order to recognize the protocol for the requested connection.

After checking protocol rules using the schema, the service checks whether any filters have called IFWXSession::AllowFutureConnect.

If the AllowFutureConnect method has been called, the filter has already checked the connection against the protocol rules. Based on the protocol rules, the filter has associated the connection with the protocol and has informed the Firewall service of the association.. This information is used by the service in this step of checking access rights.

If AllowFutureConnect has not been called, the Firewall service checks whether SetProtocol is called by a filter. If so, the filter has identified a protocol, and if allowed by the protocol rules, SetProtocol associates a connection with that protocol.

Note SetProtocol associates a connection with a protocol in response to an event, whereas AllowFutureConnect creates that association in anticipation of the event.

If a filter allows the connection, the connection request is passed to the next registered filter. If each filter allows the connection, or does not relate to the connection request, the connection is allowed. If any filter relates to the request and denies it, the connection is denied.


Asynchronous Input/Output

ISA uses asynchronous input/output (I/O) to manage multiple I/O requests simultaneously. This results in more efficient use of resources, because the Firewall service can continue I/O while waiting for particular data.

The asynchronous I/O operation takes the following steps:

  1. The data buffer object is created by the Firewall service.
  2. Data is received asynchronously.
  3. The data buffer is completed.
  4. The Firewall service sends a completion notification to one of the I/O completion methods.
  5. The completion method information is received by a Completion Notificationobject.
  6. The data buffer is available to the Firewall service and to the application filters.

For this process to take place, the application filter follows these steps:

  1. Calls an asynchronous method to issue an overlapped request.
  2. Waits for the request to be handled asynchronously and completed.
  3. Receives notification through a completion notification interface.

    Note This process differs for Win32 overlapped operations. for more information see IFWXExternalIOCompletion.

The following objects are directly related to ISA's implementation of asynchronous input/output:

  • Buffer objects that implement the IFWXIOBuffer interface.
  • Overlapped objects that implement the IFWXOverlapped interface.
  • Completion notification objects that implement the IFWXAcceptCompletion, IFWXIOCompletion, or IFWXExternalIOCompletion interface.


Filter Requirements for SecureNAT Clients

Application filters can work with Firewall clients and SecureNAT clients. This section describes specific design considerations for filters that must work with SecureNAT clients. For information on designing filters to work with Firewall clients, see Filter Requirements for Firewall Clients.

To handle SecureNAT client connect requests for outbound primary connections, the filter must register for events originating from a SecureNAT client. Use the fwxSourceNAT value of the FwxProxyEventSource enumerated type when registering for SecureNAT client events. To handle both Firewall client and SecureNAT client requests, use the macro FWX_ALL_SOURCES.

If a filter is going to handle inbound connections to SecureNAT clients, including primary connections, a specific protocol has to be registered and associated with the Connection object. Use IFWXFilterAdmin::RegisterProtocolForFilter to register the protocol, and IFWXConnection::SetProtocol to associate the protocol with the Connection object.

Inbound primary connections can be directed to the SecureNAT client using the IFWXProxy::CreatePrivateSession or IFWXProxy::GetNATSession method. Use IFWXProxy::CreatePrivateSession when the inbound connection has been requested by an application, the SecureNAT client is not known by the Firewall service, and no session object has been created. Use IFWXProxy::GetPNATSession only if the filter can assert that the client is configured to be a Secure NAT client of that server.

Use the IFWXSession::BindForClient method to permit SecureNAT clients to receive secondary inbound connections. Data filters that call IFWXSession::BindForClient and then edit addresses passed on a connection should use the fwx_dfpc_NAT value of the FwxDataFilterPriorityClass enumerated type. This places the filter as close to the client as possible, that is, it is the first data filter to receive data from the client. This is important as you want to ensure that the first filter to handle the SecureNAT data is one that is capable of doing so. For more information, see Setting Filter Priorities.

Note In a publishing scenario, mapping of the internal, Secure NAT addresses for your publishing server to external IP addresses is done using the ISA Server administration tool or the FPCPNATServerMapping object.


Filter Requirements for Firewall Clients

Application filters can work with both Firewall clients and SecureNAT clients. This section describes specific design considerations for filters that must work with Firewall clients. For information on designing filters to work with SecureNAT clients, see Filter Requirements for SecureNAT Clients.

To handle Firewall client connect requests for outgoing primary connections, the filter must register for events originating from a Firewall client. Use the fwxSourceWSP value of the FwxProxyEventSource enumerated type to register for Firewall client events. A filter that is designed to handle both Firewall client and SecureNAT client requests, should use the macro FWX_ALL_SOURCES in order to include both values.

To allow a Firewall client to receive a secondary inbound connection, use IFWXSession::RetroactiveAllowBind. Use this method because the client application may have already bound a socket on the Firewall service, and the filter should use that socket. ISession::RetroactiveAllowBind enables the previously created bind by associating it with a protocol, and also tests to see if the client application bound a proxy socket. If the client application did not bind a Firewall service socket, ISession::RetroactiveAllowBind will fail. Therefore, the filter should also call IFWXSession::BindForClient. IFWXSession::BindForClient lets a client application — for which the Firewall client component failed to create a remote socket for a bind call — receive an inbound connection.


Setting Filter Priorities

Typically, more than one data filter will be registered for the same event. The order in which data filters react to events can affect the results.

The priority coded into the data filter determines the order in which filters access data. The possible priority settings are defined in the enumerated type FwxDataFilterPriorityClass. Each priority setting is defined as being closer to the client or closer to the server. A data filter that is closer to the client is likely to be the first to examine data flowing from the client, but least likely to be the first to examine data flowing to the client. A data filter that is closer to the server is likely to be the first to examine data flowing from the server to the client, and unlikely to be the first to examine data flowing from the client to the server.

Data filter priority is important because the first data filter in a chain of data filters can affect the data received by subsequent filters.

When two or more data filters share the same priority, the order in which they address the data is arbitrary.


Application Filter Objects

Before developing application filters, it is useful to understand the basic objects related to filter function. These are:

  • Socket objects
  • Connection objects
  • Session objects
  • Filter objects
  • Session filter objects
  • Data filter objects
  • Buffer objects
  • Completion Notification objects

    Note The ISA application filter objects use a free-threaded threading model.


Socket Objects

A "socket" is an endpoint of communication — an object through which your application communicates with other Windows Sockets (Winsock) applications across a network. There are sockets on the client and on the server side.

The steps used on the client side for communication through sockets are:

  1. Open: The networking application creates a socket for a specific protocol.
  2. Bind: The socket is assigned a name (address). In TCP/IP, the application assigns a port, and may also assign an IP address if the computer is multihomed.
  3. Connect: A connection is established with the server socket, so that send and receive operations can take place. You can connect a socket for which there has been no bind, and the bind will take place as part of the connect. An explicit bind is needed only if a specific port and IP address are needed for the connection.

The steps used on the server side for communication through sockets are:

  1. Open: Create the socket.
  2. Bind: The bind is usually performed on a well-known port.
  3. Listen: Be prepared to accept connections. The listen operation takes place on the kernel level.
  4. Accept: Accept the connection and open a new socket for it. This socket is passed to the application so that it can communicate with the client. The listening socket continues to listen for additional connect requests, so that other accept functions can take place.

For more information on sockets, see MSDN. See Socket Implementation in ISA for specifics about using sockets with this product.


Socket Implementation in ISA

Each data filter works with two objects that implement a socket interface. One represents the internal socket and the other represents the external socket, and the filter pumps data between them.

ISA has two interfaces through which you can manage socket activity:

  • IFWXSocket
  • IFWXNetworkSocket

IFWXSocket

IFWXSocket is the interface for a socket that was opened by the Firewall service. The IFWXSocket interface has limited functionality; its methods allow you to send and receive on the socket, or to close the socket.

IFWXSocket's limited functionality is intentional: A data filter that uses two IFWXSocket interfaces to send and receive data does not know whether it is communicating with the Internet, the client, or another data filter in a chain of data filters.

Because IFWXSocket is for use only with existing sockets, there is no allowance for functions such as bind or connect.

IFWXNetworkSocket

The IFWXNetworkSocket interface is an extension of the IFWXSocket interface. IFWXNetworkSocket represents a true socket object for either the client or server. It allows you to establish a socket, then use the IFWXSocket functionality to perform send and receive operations. Therefore, in addition to the send, receive, and close functions of IFWXSocket, IFWXNetworkSocket provides methods such as Bind, Connect and Listen.

The socket object for IFWXNetworkSocket can be created using either IFWXProxy::CreateNetworkSocket or IFWXSession::CreateNetworkSocket. In either case, the socket object created using CreateNetworkSocket has full socket functionality for operations such as opening a packet filter or working with chained ISA Server computers.

A socket created using IFWXProxy::CreateNetworkSocket is not user specific. An example of a socket that should not be user-specific is a listening socket.

To create a user-specific socket, use IFWXSession::CreateNetworkSocket. The socket created by IFWXSession::CreateNetworkSocket has the same functionality as that created by IFWXProxy::CreateNetworkSocket, but because it is user specific, its activities can be logged, and ISA's policies apply to it. The use of this kind of socket is appropriate when a filter will be making a connection for a specific user.

Warning

There are three reasons to create Windows Sockets (Winsock) for ISA only through the CreateNetworkSocket method:

  • The application filters and the Firewall service should use the same thread pool, and thus the same completion port.
  • With IFWXNetworkSocket, the filter becomes part of the dynamic packet filtering scheme. A socket created using Firewall service interfaces would not be able to connect to an external address when packet filtering is enabled.
  • Proxy chaining is supported only by IFWXNetworkSocket.


Connection Objects

Connection objects provide a means for the Firewall service to perform services for a client socket. For those specific services, such as setting up a remote socket for a client socket, the connection object represents the client socket to the Firewall service. When a Firewall client uses bind, connect, or sendto Winsock functions, and the client DLL identifies a remote destination, the Firewall service creates a connection object that resides on the server.

Similarly, a connection object will be generated for a SecureNAT client. In the case of the SecureNAT client, the Firewall service first receives the request from the client, identifies it as originating from a SecureNAT client, and then creates the connection object and proceeds.

Connection objects are also created when BindForClient is called. In this case, an application filter, rather than the Firewall service, identifies that the client called bind.

Connection objects implement the IFWXConnection interface. For examples of how the Firewall service uses the IFWXConnection interface, see IFWXConnection in Basic Filter Interfaces.


Session Objects

A session is a group of connections that are related because they are associated with a particular client. For Firewall clients, a session is created for each control channel. For SecureNAT clients, a session is created for each client IP address.

The Firewall service creates a session object for each session. The session object can be used to query about the user that made the connection and the user's permissions, for modifying the permissions of future connections, and for performing network operations on behalf of the application. The session object provides specific functionality through the IFWXSession interface, including the following:

  • Retrieving the name or address of the user's computer.
  • Allowing inbound connections for an existing bind.
  • Creating a bind on behalf of a client.
  • Impersonating the user's account.
  • Querying the Firewall service about a user's access rights.
  • Creating a user-specific socket for a client.


Filter Objects

Each application filter is represented by a filter object called FWXFilter. The FWXFilter object implements the IFWXFilter interface, used by the Firewall service to load and initialize the application filter, and to create session filters.


Session Filter Objects

A session filter is created and attached to a session when the Firewall service detects an event for which the application filter has registered. By being attached to the session, the session filter can receive notification events and react to them. For example, a session filter could react to a notification event by placing a data filter on the session data.

Each session filter is represented by an FWXSessionFilter object implementing the IFWXSessionFilter interface.


Data Filter Objects

A session filter may, in response to an event, ask the Firewall service to attach a data filter to a session. The data filter is provided with an internal and external socket, and functions as a data pump between the two sockets. The data filter is represented by an object that implements the IFWXDataFilter interface.


Buffer Objects

ISA handles data in data buffers. Each data buffer is represented by a buffer object. By using pointers to the buffer object, various components such as a series of filters can use the same data without the need to copy data. Avoidance of data copy improves performance.

A buffer's size is defined in two ways:

  • Allocated size
  • Actual size

The allocated size is the buffer's capacity in bytes, and does not reflect data actually stored in the buffer. When a buffer is created and filled by a filter, it begins with a defined allocated size. The actual size is the number of bytes of data the buffer currently holds.

A filter can perform the following buffer management activities:

  • Read into a buffer directly from a memory pointer using the IFWXIOBuffer::Append method.
  • Read a buffer using the IFWXIOBuffer::GetBufferAndSize method.
  • Read a portion of a buffer using the IFWXIOBuffer::ReadAt method.
  • Send data from a buffer to another buffer using the IFWXIOBuffer::SendToBuffer method.
  • Manipulate the memory directly using IFWXIOBuffer::GetBufferAndSize method.
  • Reset the buffer size using IFWXIOBuffer::SetDataSize method.

For more information regarding these methods, see IFWXIOBuffer.

Buffer objects implement the IFWXIOBuffer interface.

Using the IFWXIOBuffer interface, information about the buffer can be retrieved and the buffer can be modified. For examples of how the Firewall service uses the IIOBuffer interface, see Basic Filter Interfaces.


Completion Notification Objects

Completion notification objects work with Completion Port objects, also known as I/O Completion Port objects, to allow the operating system to handle multiple threads efficiently for asynchronous I/O. For more information on use of completion ports in Windows, see MSDN. The firewall service completion port is a completion port requested by the Firewall service from Windows 2000 that remains associated with the service. The completion port is associated with a number of client connections. All I/O operations should make use of the firewall service completion port so that I/O operations take place efficiently.

To use a completion port you need to provide an I/O Completion Notification object that will receive notification when the I/O operation has completed. Hook the handle to the firewall service completion port using the IFWXProxy::HookToCompletionPort method. The firewall service provides the Overlapped object, completion port de-queuing, and the thread pool. To receive notification that the I/O has been completed, use the IFWXOverlapped::SetNotificationInterface method.

Asynchronous I/O and Completion Ports

When an asynchronous I/O operation has been completed on a particular connection, the Firewall service notifies the completion port using one of three completion notification methods:

  • IFWXIOCompletion::CompleteAsyncIO
  • IFWXAcceptCompletion::CompleteAsyncAccept
  • IFWXExternalIOCompletion::CompleteAsyncIO

Each of these methods includes a Boolean succeed/fail parameter, a Win32® error code parameter, and a user-data parameter that provides user-context information. However, the method used by the firewall service to send the notification depends on the type of I/O operation that has been completed.

IFWXIOCompletion::CompleteAsyncIO

This is the general method for receiving notification from the Firewall service when an asynchronous I/O operation is completed. When a data buffer has been completed through an asynchronous I/O operation, the notification is sent to IFWXIOCompletion::CompleteAsyncIO.

IFWXAcceptCompletion::CompleteAsyncAccept

This method receives notifications from the Firewall service when an IFWXNetworkSocket:Accept is completed on a listening socket.


IFWXExternalIOCompletion::CompleteAsyncIO

IFWXExternalIOCompletion::CompleteAsyncIO is the I/O completion notification used with asynchronous I/O for operating system files. If the Firewall service has a handle for an operating system file, and needs to call the file or write to it, this operation will be asynchronous, so that it can take place in the background. An example of an asynchronous I/O operation for operating system files is writing to or reading from a disk.

There are four sequential steps to this process:

  1. The Firewall service calls IFWXProxy::HookToCompletionPort, which connects the file handle to the service's completion port. This step takes place once per connection.
  2. The Firewall service calls IFWXProxy::CreateOverlapped to create the Overlapped object, which implements the IFWXOverlapped interface.
  3. The Firewall service uses IFWXOverlapped::GetOverlapped to get a pointer to the Winsock OVERLAPPED structure, and IFWXOverlapped::SetNotificationInterface to send notification when the I/O operation has been completed.
  4. IFWXExternalIOCompletion::CompleteAsyncIO receives the notification, including a succeed or fail message, information regarding the user, and the number of bytes transferred.

The following figure summarizes the process of asynchronous I/O for operating system files.


Filter Object Model

When the Firewall service starts, it implements the IFWXProxy interface.

The Firewall service creates application filter instances. Each application filter implements the IFWXFilter interface. The Firewall service initializes the application filter using the IFWXFilter::FilterInit.

The application filter registers for events. When the Firewall service detects an event for which the application filter is registered, it uses the IFWXFilter::AttachToSession to inform the application filter that the event has occurred. The application filter then creates an instance of the session filter, which implements IFWXSessionFilter.

The session filter object refers to the session object, represented by the IFWXSession interface, for client and user information.

When an event is detected that the filter is interested in, as indicated in the output of IFWXFilter::AttachToSession, the Firewall service notifies the filter by calling the IFWXSessionFilter::FwxProxyEventHandler method.

When it is notified by the Firewall service that an event the filter is interested in has occurred, the session filter can create an instance of a data filter, which implements the interface IFWXDataFilter. Alternatively, data filters can be created by using IFWXSession::SetDataFilterFactory. The session filter object attaches the data filter to the connection related to the specific event. The connection implements the IFWXConnection interface.

IFWXConnection provides the data filter with the internal and external sockets using IFWXDataFilter::SetSockets. Each socket object implements the IFWXSocket interface. The data filter then performs the data pumping and filtering for a specific connection.

Data is received as buffers. To avoid the need to copy buffers, each buffer is handled as an object, FWXIOBuffer, that implements the IFWXIOBuffer interface. Since data is received asynchronously, the data filter must implement IFWXIOCompletion, which is necessary for asynchronous input/output (I/O) on the sockets. When an asynchronous I/O operation is completed, the Firewall service uses IFWXIOCompletion::CompleteAsyncIO to notify the data filter that the buffer is available to it.

The data filter can then perform its filtering function on the data buffer.

Filter registration procedures are described in Filter Setup.

The phases of a filter's operation are shown in the following figure. See ConnectorFilter for a diagram that illustrates the logic of a specific filter.


Filter Development

This section describes the tools provided by ISA to develop application filters and the application filter development process. This section contains the following topics:

  • Filter Development Tools
  • Filter Development Process
  • Best Practices


Filter Development Tools

ISA provides the tools you need to develop application filters. This section describes those tools.

The section contains the following topics:

  • Header and .Idl Files Provided with ISA
  • Application Filter Interfaces


Header and .Idl Files Provided with ISA

The ISA SDK provides you with the .h and .idl files needed to create a filter. You need to include the appropriate SDK files in your project. For an example of how to do this, see the procedure in How to Create an Application Filter.

The SDK files include:

  • wspfwext.idl
  • wspfwtyp.h
  • wspfwerr.h
  • msfpccom.idl
  • fpcimports.h
  • fpcimports.idl

Of these, wspfwext.idl and msfpccom.idl are of the greatest interest to filter developers.

wspfwext.idl

The wspfwext.idl file contains the definitions and globally unique identifiers (GUIDs) of the object interfaces. When you first compile your project, the files wspfwext.h and wspfwext_i.c are generated from wspfwext.idl.

wspfwtyp.h

Defines Windows and WinSock structures for the Microsoft Interface Definition Language (MIDL) compiler, which compiles the .idl files.

wspfwerr.h

Contains error code definitions for the Firewall service.

msfpccom.idl

The msfpccom.idl contains the definitions of the ISA administration COM objects.

fpcimports.h

Allows inclusion of standard system header files in an .idl file. Works with cometimports.idl. For more information, see the section on importing system header files in MSDN.

fpcimports.idl

Allows inclusion of standard system header files in an .idl file. Works with cometimports.h. For more information, see the section on importing system header files in MSDN.


Application Filter Interfaces

There are 18 interfaces defined in the wspfwext.idl file. Of these, the filter implements six interfaces, the Firewall service implements 11, and one interface can be implemented by either the service or the filter. See the Reference section for detailed descriptions of interfaces.

This section contains the following topics:

  • Basic Filter Interfaces
  • Advanced Filter Interfaces


Basic Filter Interfaces

Basic filter development will require that you work primarily with the following interfaces:

Interface | Implementation
IFWXFilter | Implemented by the application filter.
IFWXSessionFilter | Implemented by the application filter.
IFWXDataFilter | Implemented by the application filter.
IFWXConnection | Implemented by the firewall service.
IFWXSocket | Implemented by the firewall service.
IFWXProxy | Implemented by the firewall service.
IFWXSession | Implemented by the firewall service.
IFWXFilterAdmin | Implemented by the firewall service.

These interfaces are introduced in this section. They are described in the order in which they typically might be used in code.


IFWXFilter

The Firewall service uses the IFWXFilter interface to load and initialize a filter and to create session filters. An IFWXFilter interface is called for each filter that is in ISA storage and is enabled.

Notes to Implementers

IFWXFilter is the first interface that you need to implement.

In IFWXFilter you define a port, or range of ports, to be monitored, and the events that will trigger a call to the IFWXFilter::AttachToSession method.

Note There are situations where threading issues require caution in the implementation of IFWXFilter::FilterShutdown. For more information, see the Reference section.

ISA Samples that Use IFWXFilter Methods

The methods IFWXFilter::FilterInit, IFWXFilter::FilterShutdown, and IFWXFilter::AttachToSession are used in the following sample filters provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

Example Code

Following are examples of code to implement IFWXFilter methods:

:

IFWXFilter::FilterInit

HRESULT STDMETHODCALLTYPE
CMyFWXFilter::FilterInit(
IFWXProxy         * pProxyInterface,
FwxFilterHookEvents ** ppFilterHookEvents)
{
    //Listening on port <range>
        m_FwxPortRangeEvents.StartPort=<start range>;
        m_FwxPortRangeEvents.EndPort=<end range>;

    //Initialize events
        m_FwxPortRangeEvents.dwSocketEvents=<FwxProxyEventSource>
                        | <FwxProxyEventType>;
        m_FwxFilterHookEvents.dwGlobalEvents=<FwxProxyEventSource>
                        | <FwxProxyEventType>;
        m_FwxFilterHookEvents.dwNumPortRanges = <No. of entries in     FwxPortRangeEvents>;
        m_FwxFilterHookEvents.FwxPortRangeEvents = &m_FwxPortRangeEvents;

    m_spProxy = pProxyInterface;
    return m_spProxy->DuplicateFilterHookEvents(
    &g_MyHookEvents,
    ppFilterHookEvents);
}

IFWXFilter::AttachToSession

HRESULT STDMETHODCALLTYPE AttachToSession(
    /* [in] */ IFWXSession __RPC_FAR *piSession,
    /* [out] */ IFWXSessionFilter __RPC_FAR *__RPC_FAR *piSessionFilter,
    /* [out] */ PFwxFilterHookEvents __RPC_FAR *ppFilterHookEvents)
{
CComObject<CMyFWXSessionFilter> *pMySessionFltr;
CComObject<CMyFWXSessionFilter>::CreateInstance(
                        &pMySessionFltr);
// Other initializations here.

pMySessionFltr->QueryInterface(
                        IID_IFWXSessionFilter,
                        ppISessionFilter);

m_spProxy->DuplicateFilterHookEvents(
                        &g_MySecondaryHookEvents,
                        ppFilterHookEvents);
}


IFWXSessionFilter

The filter implements the IFWXSessionFilter interface in order to monitor and react to events in a given session.

Notes to Implementers

This is the second interface for which you need to write code, and which must be implemented by each application filter. This is the interface typically used for attaching a data filter to a session.

The interface is implemented on each session filter object. A different combination of session filters can be attached to each user session. However, a session filter is usually attached to a single user session.

Remarks

In the IFWXSessionFilter::FwxProxyEventHandler method select an action based on the event data provided by the Firewall service.

In IFWXSessionFilter::Detach you would typically release references to other objects.

ISA Samples that Use IFWXSessionFilter Methods

The method IFWXSessionFilter::FwxProxyEventHandler is used in the following sample filters provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXSessionFilter::Detach is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • SMTPFLTR

Example Code

Following are examples of code to implement IFWXSessionFilter methods.

IFWXSessionFilter::FwxProxyEventHandler

HRESULT
CMyFWXSessionFilter::FwxProxyEventHandler(
                    ProxyEvent *pEvent)
{
    switch (pEvent->EventType) {
    case fwx_Connect_Tcp:
        // Handle connect event
    case fwx_Accept:
        // Handle accept event
…
}

IFWXSessionFilter::Detach

    HRESULT
    CMyFWXSessionFilter::Detach()
{
    // Assuming that m_spSession is defined
    // as CComPtr<IFWXSession>, IFWXSession::Release() is called
    // by the assignment operator.
    Lock();
    m_spSession = NULL;
    Unlock();

    return S_OK;
}


IFWXDataFilter

IFWXDataFilter is the interface for a data filter. The data filter functions as the Firewall service's data pump, and performs the data filtering.

Notes to Implementers

Filters that examine data require a data pump to pass data through the connection.

There are two approaches to creating data filter instances:

  1. Implement IFWXConnection::AttachDataFilter to create and attach a data filter by adding code to the session filter. The session filter will then attach a data filter instance to the connection whenever the registered event occurs.
  2. Provide an object that implements the standard COM IClassFactory interface. An example of this approach is provided in How to Create an Application Filter.

Remarks

Implement the IFWXConnection interface methods (implemented by the Firewall service) to attach the data pump, and IFWXSessionFilter::FwxProxyEventHandlerto receive information about the event. Through the IFWXDataFilter::SetSockets method, the Firewall service provides socket interfaces to the data filter for the sockets on the internal and external computers. The Firewall service calls the IFWXDataFilter::Detach method when the connection to the sockets is no longer needed. When IFWXDataFilter::Detach is called you must code a release to the sockets so that the system can delete the socket objects.

The Firewall calls IFWXIOCompletion::CompleteAsyncIO when the I/O operation is completed. The data filter object inherits the CompleteAsyncIO method from IFWXIOCompletion. The data is then available for the data pump and filter.

Handling Data Received from Another Protocol

When the primary port of a protocol lies within the dynamic port range (1024 – 5000), a filter for that protocol will receive a proxy event if that port is selected for another protocol's secondary connection. However, when the data stream through that secondary connection does not comply with the filter's expected protocol, the filter must be able to handle this situation gracefully.

The proper approach is to design your filter to revert to a simple data pump if the data stream is not the expected protocol. Note that it is possible in this way for data that would have been rejected at the primary port to pass through the filter at the secondary port.

ISA Samples that Use IFWXDataFilter Methods

The method IFWXDataFilter::SetSockets is used in the following sample filters provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXDataFilter::Detach is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • SMTPFLTR

Example Code

Standard Declaration of Data Filter Object

//Note that IFWXIOCompletion::CompleteAsyncIO is made
//public in this declaration, and must be implemented
//by this object.
class ATL_NO_VTABLE CDumpData :
    public CComObjectRootEx<CComMultiThreadModel>,
    public IFWXDataFilter,
    public IFWXIOCompletion
{

IFWXDataFilter::SetSockets

STDMETHODIMP
//DumpData is the name of object that implements
//IFWXFilter in this example
CDumpData::SetSockets(
    IN   IFWXSocket *piInternalSocket,
    IN   IFWXSocket *piExternalSocket,
    IN   IFWXConnection *piConnection,
    IN   IUnknown *punkFilterContext
    )
{
    // Using Lock/Unlock, all access to the sockets is protected
    // because Detach could be called at any time.
    Lock();
    m_spInternalSocket = piInternalSocket;
    m_spExternalSocket = piExternalSocket;
    Unlock();
    //ReadFirstBuffer is a function that waits for
    //data on both sockets.
    return ReadFirstBuffers();
}

The variables m_spInternalSocket and m_spExternalSocket are defined as follows:

    CComPtr<IFWXSocket>    spExternalSocket = m_spExternalSocket;
    CComPtr<IFWXSocket>    spInternalSocket = m_spInternalSocket;

Simple Implementation of CompleteAsyncIO

STDMETHODIMP
//DumpData is the name of object in this example
CDumpData::CompleteAsyncIO(
    IN BOOL      fSuccess,
    IN DWORD     Win32ErrorCode,
    IN IFWXIOBuffer *pIOBuffer,
    IN DWORD     dwUserData,
    IN PSOCKADDR From,
    IN INT       FromLen
    )
{
    DWORD NumberOfBytesTransfered = 0;
    PBYTE pbBuffer;
    BOOL  fShutdown;
    char *pszReadSource;
    IFWXSocket *piSocket;

    // Set the target socket for the buffer.
    if (dwUserData == ReadFromInternal) {
        piSocket   = GetExternalSocket();
        pszReadSource = "Internal";
    } else {
        piSocket = GetInternalSocket();
        pszReadSource = "External";
    }

    if (fSuccess && pIOBuffer) {
        pIOBuffer->GetBufferAndSize(&pbBuffer,
                                &NumberOfBytesTransfered);

    if (piSocket == NULL) {
        return S_OK;                    // Detach was called
    }
//This particular filter just receives and sends the data.
//This is the point in the code where a filter's functionality
//should be inserted.
    // Send the buffer
    if (!fSuccess || NumberOfBytesTransfered == 0) {
        fShutdown = TRUE;
        piSocket->Shutdown(!fSuccess);
    }
        else {
        fShutdown = FALSE;
        if (From == NULL) {
            piSocket->Send(pIOBuffer, NULL, 0);
        } else {
            piSocket->SendTo(pIOBuffer, From, FromLen, NULL, 0);
        }
    }

    piSocket->Release();

    if (fShutdown) {
        return S_OK;
    }

    // Read another buffer
    piSocket = dwUserData == ReadFromInternal ?
        GetInternalSocket() : GetExternalSocket();

    if (piSocket == NULL) {
        return S_OK;
    }

    piSocket->Recv(NULL, this, dwUserData);

    piSocket->Release();

    return S_OK;
}


IFWXIOCompletion

All overlapped operations require the filter to implement this interface in order to carry out data pumping.

Notes to Implementers

When calling a method that begins an overlapped operation, the filter must pass to that method a pointer to the IFWXIOCompletion interface. The Firewall service calls the IFWXIOCompletion interface of the filter when the overlapped operation completes.

ISA Samples that Use IFWXIOCompletion Methods

The method IFWXIOCompletion::CompleteAsyncIO is used in the following sample filters provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

Example Code

See Simple Implementation of CompleteAsyncIO in the IFWXDataFilter topic earlier in this section.


IFWXConnection

The connection object represented by the IFWXConnection interface implements functions specific to a particular connection. Each remote socket created for a client has a connection object associated with it.

The IFWXConnection methods are understood most easily in the context of connection scenarios:

Scenario A: Bind/Connect

  1. The client requests a bind or connection.
  2. The Firewall service creates a Connection object.
  3. The Firewall service checks access rights.
  4. The Firewall Service provides an event notification to the application filters, so that the filters can then work with the Connection object and use:
    • IFWXConnection::Deny, to deny the connection.
    • IFWXConnection::AttachDataFilter, to attach a data filter to this connection. In the case of a bind request, this applies to UDP only.
    • IFWXConnection::SetProtocol to establish that the connection is for a particular protocol, and to inform the Firewall service whether the connection will be emulated.

Scenario B: Bind/Listen

  1. The client requests a bind.
  2. The filter calls IFWXSession::BindForClient.
  3. The Firewall service creates a Connection object.
  4. The Firewall service provides an event notification to the application filter, so that the filter can then work with the Connection object.

When a listening socket exists, and a fwx_AcceptedConnection event occurs, an accepted socket is created on the Firewall service. The Connection object for the accepted socket exists before the matching client socket is created.

Notes to Implementers

When a registered event occurs, the Firewall service will call FwxProxyEventHandler, and will pass the ProxyEvent parameter to it. Included in the ProxyEvent parameter is a pointer to IFWXConnection.

Once the pointer is available you can use the methods such as IFWXConnection:AttachDataFilter.

Sample Filters that Use IFWXConnection Methods

The method IFWXConnection::AttachDataFilter is used in the following sample filters provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock

The method IFWXConnection::GetExternalSocketName is used in the following sample provided with ISA:

  • ConnectorFilter

The method IFWXConnection::Deny is used in the following samples provided with ISA:

  • ExeBlock
  • ServerSplit

The method IFWXConnection::EmulateConnection is used in the following sample provided with ISA:

  • ServerSplit

The method IFWXConnection::SetProtocol is used in the following samples provided with ISA:

  • ServerSplit
  • SMTPFLTR

The method IFWXConnection::SetSocketName is used in the following sample provided with ISA:

  • ServerSplit

Typical Implementations

Implemented by the Firewall service.


IFWXSocket

The IFWXSocket interface is the Firewall service socket interface. This interface does not create the socket; rather, it allows the data filter to work with data that is flowing through the socket.

The socket itself is created using the IFWXNetworkSocket interface.

For more information on sockets and socket interfaces, see Socket Objects.

Samples that Use IFWXSocket Methods

The method IFWXSocket::Close is used in the following sample filters provided with ISA:

  • ConnectorFilter
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXSocket::Recv is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXSocket::Send is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXSocket::SendTo is used in the following samples provided with ISA:

  • DbgDump
  • ServerSplit

The method IFWXSocket::Shutdown is used in the following samples provided with ISA:

  • DbgDump
  • ServerSplit

Typical Implementations

Implemented by the Firewall service.


IFWXIOBuffer

The buffer class holds a reference-counted memory buffer. The IFWXOBuffer object is a wrapper around a memory buffer. This allows the buffer to be utilized by many filters in a chain, avoiding inefficient copying of buffers. For more information on memory buffers, see Buffer Objects.

Notes to Implementers

Consider carefully the size of the buffer needed. Data length information provided on the Internet may be inaccurate, resulting in buffer overload.

IFWXIOBuffer is generally implemented by the Firewall service. However, you may want the filter to implement IFWXIOBuffer in either of the following circumstances:

  • You already have an allocated buffer that you want to send, and want to avoid a buffer copy. For example, the buffer was received from an RPC call or an API that cannot work with Firewall servicebuffers.
  • You want to import data into a preallocated buffer.

You can rely on the Firewall service's implementation of IFWXIOBuffer, and not code a filter implementation, if:

  • You want to send a constant buffer.
  • You want to send a section of another buffer.
  • Your filter can handle or parse the data from IFWXIOBuffer.
  • Buffer copy is not of concern.

Samples that Use IFWXIOBuffer Methods

The method IFWXIOBuffer::Append is used in the following sample filters provided with ISA:

  • ConnectorFilter
  • ExeBlock

The method IFWXIOBuffer::GetBufferAndSize is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXIOBuffer::SetDataSize is used in the following sample provided with ISA:

  • ExeBlock


IFWXProxy

The IFWXProxy interface provides functions for filters that are not tied to any specific user session.

The Firewall service implements this interface and passes it to the IFWXFilter::FilterInit method.

Notes to Implementers

The IFWXProxy::DuplicateFilterHookEvents method is used in every filter. For a usage example see IFWXFilter::FilterInit.

Samples that Use IFWXProxy Methods

The method IFWXProxy::CreateBuffer is used in the following sample filters provided with ISA:

  • ConnectorFilter
  • ExeBlock

The method IFWXProxy::DuplicateFilterHookEvents is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXProxy::CreateConstBuffer is used in the following sample provided with ISA:

  • ExeBlock

The method IFWXProxy::CreateNetworkSocket is used in the following sample provided with ISA:

  • ServerSplit

The method IFWXProxy::CreateOverlapped is used in the following sample provided with ISA:

  • ExeBlock

The method IFWXProxy::HookToCompletionPort is used in the following sample provided with ISA:

  • ExeBlock

The method IFWXProxy::GetPNATSession is used in the following sample provided with ISA:

  • SMTPFLTR

Typical Implementations

Implemented by the Firewall service.


IFWXSession

The IFWXSession interface is used to attach a data filter to a session, and to monitor the session's events.

The session object implements session-specific functions that impersonate the user's account, test ACLs against the session's user, get information about the client computer, and perform protocol operations.

Samples that Use IFWXSession Methods

The method IFWXSession::AccessCheck is used in the following sample filter provided with ISA:

  • ExeBlock

The method IFWXSession::AllowFutureConnect is used in the following sample provided with ISA:

  • ConnectorFilter

The method IFWXSession::BindForClient is used in the following sample provided with ISA:

  • ConnectorFilter
  • SMTPFLTR

The method IFWXSession::GetClientAddress is used in the following sample provided with ISA:

  • DbgDump

The method IFWXSession::GetClientMachineName is used in the following sample provided with ISA:

  • DbgDump

The method IFWXSession::GetSessionFlags is used in the following sample provided with ISA:

  • ConnectorFilter

The method IFWXSession::RetroactiveAllowBind is used in the following sample provided with ISA:

  • ConnectorFilter

Typical Implementation

Implemented by the Firewall service.


IFWXFilterAdmin

The IFWXFilterAdmin interface is used by the filter for installation and configuration. You must use this interface to install a filter.

Notes to Implementers

Create an instance of the FWXFilterAdmin class in order to use these administration methods.

ISA Samples that Use IFWXFilterAdmin Methods

The method IFWXFilterAdmin::InstallFilter is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXFilterAdmin::UninstallFilter is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXFilterAdmin::RegisterProtocolForFilter is used in the following samples provided with ISA:

  • ConnectorFilter
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXFilterAdmin::UnregisterProtocolForFilter is used in the following sample provided with ISA:

  • SMTPFLTR

The method IFWXFilterAdmin::GetProtocol is used in the following samples provided with ISA:

  • ConnectorFilter
  • SMTPFLTR

The method IFWXFilterAdmin::GetFilterParameterSet is used in the following sample provided with ISA:

  • SMTPFLTR

Example Code

The code for registering filters and protocols should be written in the .cpp file that represents the filter object. The filter uses this interface primarily in the DllRegisterServer and DllUnregisterServer functions.

Code for Registering the Filter Object

//Create the FWXFilterAdmin object
HRESULT ProxyReg()
{
    HRESULT hr;
    IFWXFilterAdmin *ifa = NULL;

    hr = CoCreateInstance(
        CLSID_FWXFilterAdmin,
        NULL,
        CLSCTX_SERVER,
        IID_IFWXFilterAdmin,
        (void**)&ifa);
    if (FAILED(hr)) return hr;

    //Register the class as a filter
    hr = ifa->InstallFilter(
        CLSID_EBFilter,

        L"Sample filter",
        L"Long description here..",
        L"1.0",
        NULL);
    ifa->Release();

    return hr;
}

Code for Protocol Registration

// HRESULT hr;
// IFWXFilterAdmin *ifa;

hr = ifa->RegisterProtocolForFilter(
    CLSID_FTPFilter,
    L"FTP",
    L"FTP protocol via ftpfltr filter",
    NULL);


Advanced Filter Interfaces

In addition to the 10 interfaces described in Basic Filter Interfaces, there are eight interfaces that provide additional functionality for application filters:

  • IFWXAcceptCompletion
  • IFWXExternalIOCompletion
  • IFWXImpersonator
  • IFWXNetworkSocket
  • IFWXOverlapped
  • IFWXProxyAction
  • IFWXGetXByY
  • IFWXSlowDataFilter


IFWXAcceptCompletion

The IFWXAcceptCompletion interface has one method, CompleteAsyncAccept. This method receives notifications from the Firewall service when an IFWXNetworkSocket:Accept method is completed on a listening socket. For more information, see IFWXAcceptCompletion::CompleteAsyncAccept in the Reference section.

Typical Implementations

Implemented by the Firewall service.


IFWXExternalIOCompletion

The IFWXExternalIOCompletion interface has one method, CompleteAsyncIO. This method receives notifications from the Firewall service when an asynchronous I/O operation on an operating system file (such as writing to or reading from a disk) is completed. For more information, see IFWXExternalIOCompletion::CompleteAsyncIO in the Reference section.

Typical Implementations

Implemented by the Firewall service.

Example Code

This example of an implementation of IFWXExternalIOCompletion::CompleteAsycnIO is taken from the Exeblock sample filter.

HRESULT
STDMETHODCALLTYPE
CEBScannerDataFilter::CompleteAsyncIO(
    /* [in] */ BOOL fSuccess,
    /* [in] */ DWORD NumberOfBytesTransfered,
    /* [in] */ DWORD Win32ErrorCode,
    /* [in] */ IFWXOverlapped __RPC_FAR *pOverlapped,
    /* [in] */ UserContextType UserData)
{

    if (!fSuccess) _Abort();
    pOverlapped->Release();
    IFWXSocket *pISocket = _GetExternalSocket();

    if (pISocket) {
        pISocket->Recv(NULL, this, 0);
        pISocket->Release();
    }

    return S_OK;
}

ISA Samples that Use IFWXExternalIOCompletion Methods

The method IFWXExternalIOCompletion::CompleteAsyncIO is used in the following sample provided with ISA:

  • Exeblock


IFWXImpersonator

The IFWXImpersonator object holds user information so that the Firewall service can impersonate the user. When a filter implements IFWXImpersonate, IFWXSession::ImpersonateClient calls IFWXImpersonate::Impersonate and IFWXSession::RevertToSelf calls IFWXImpersonate::RevertToSelf.

Impersonators must be implemented as in-process servers.

Notes to Implementers

The filter can implement IImpersonator when using a private session if the filter can authenticate the user. The authentication may be on the protocol level, or for out-of-band communication.

For more information about private sessions, see IFWXFilter::CreatePrivateSession.

Typical Implementations

Implemented by the Firewall service.

Example Code

class CFWXImpersonator :
    public CComObjectRootEx<CComMultiThreadModel>,
    public IFWXImpersonator {

public:

    BEGIN_COM_MAP(CFWXImpersonator)
        COM_INTERFACE_ENTRY(IFWXImpersonator)
    END_COM_MAP()

    // IFWXImpersonator
    HRESULT STDMETHODCALLTYPE Impersonate(void) {
        HRESULT hr = S_OK;
                if (!ImpersonateLoggedOnUser(m_token)) {
              hr = HRESULT_FROM_WIN32(GetLastError());
                }
                return hr;
      }

    HRESULT STDMETHODCALLTYPE RevertToSelf(void) {
           HRESULT hr = S_OK;
        if (!RevertToSelf()) {
        hr = HRESULT_FROM_WIN32(GetLastError());
        }

        return hr;
      }

      // Initialize from a token handle
    HRESULT Initialize(HANDLE token) { m_token = token; return S_OK; }
      // Initialize from username + password
      HRESULT Initialize(LPCSTR UserName, LPCSTR Domain, LPCSTR Password) {
             if (LogonUser(
                 UserName,
                 Domain,
                 Password,
                 LOGON32_LOGON_NETWORK,
                 LOGON32_PROVIDER_DEFAULT,
                 &m_hToken)) return S_OK;
             else {
                return HRESULT_FROM_WIN32(GetLastError());
              }
      }
private:
    HANDLE m_token;
};


IFWXNetworkSocket

The IFWXNetworkSocket interface is an extension of the IFWXSocket interface. IFWXNetworkSocket represents a true socket object for either the client or server. The socket object for IFWXNetworkSocket can be created using either IFWXProxy::CreateNetworkSocket or IFWXSession::CreateNetworkSocket. For more information see Socket Implementation in ISA, or IFWXNetworkSocket.

ISA Samples that Use IFWXNetworkSocket Methods

The method IFWXNetworkSocket::Accept is used in the following sample filter provided with ISA:

  • ServerSplit

The method IFWXNetworkSocket::Bind is used in the following sample provided with ISA:

  • ServerSplit

The method IFWXNetworkSocket::Listen is used in the following sample provided with ISA:

  • ServerSplit

Typical Implementations

Implemented by the Firewall service.


IFWXOverlapped

If the Firewall service is performing asynchronous I/O for an operating system file, it must have access to the Windows Sockets OVERLAPPED structure and a means of setting up a callback when the I/O is completed.

IFWXOverlapped gets a pointer to the Windows Sockets OVERLAPPED structure. The IFWXOverlapped object also provides the link between the OVERLAPPED structure and a completion notification interface, and includes user context information that allows the filter to distinguish between different notifications.

Notes to Implementers

First use the IFWXOverlapped::SetNotificationInterface method to set the notification interface and user-context. Then use the IFWXOverlapped::GetOverlapped method to get an OVERLAPPED structure that will be used in a call to an asynchronous Win32 API.

The call to the WIN32 API must use a handle that is associated with the Firewall service's completion port. For more information, see IFWXProxy::HookToCompletionPort.

When the overlapped operation completes, the Firewall service will get the completion notification in its completion port, and will call the completion notification method of the specified interface.

Samples that Use IFWXOverlapped Methods

The method IFWXOverlapped::GetOverlapped is used in the following sample filter provided with ISA:

  • ExeBlock

The method IFWXOverlapped::SetNotificationInterface is used in the following sample provided with ISA:

  • ExeBlock


IFWXProxyAction

A filter may request that the Firewall service perform a proxy action, such as connecting to a certain target, in response to a proxy event or address. A proxy action is always requested in anticipation of an event that may not occur. This interface permits cancellation of the proxy action request. Typically, a proxy action relates only to events for which a filter is not registered.

For example, if the action is the future establishment of a secondary connection, IFWXProxyAction can be used to cancel the action if the primary connection is terminated.

Remarks

The proxy may automatically cancel certain actions, including:

  • Actions that are supposed to happen only once (the action is canceled after its first occurrence).
  • Actions that have a time-out
  • An action associated with a session that has been killed.

ISA Samples that Use IFWXProxyAction Methods

The method IFWXProxyAction::Cancel is used in the following sample filter provided with ISA:

  • ConnectorFilter

Typical Implementations

Implemented by the Firewall service.


IFWXGetXByY

IFWXGetXByY allows you to override the gethostbyname or gethostbyaddr function. A typical use of IFWXGetXByY is to return an IP address other than that requested by the client, thus redirecting the request. IFWXGetXByY can also cause the gethostbyname and gethostbyaddr functions to fail, so that the Firewall service will return a "Host Not Found" message.

Notes to Implementers

The filter must call this interface from within the IFWXSessionFilter::ProxyEventHandler function.

Typical Implementations

Implemented by the application filter..


IFWXSlowDataFilter

A data-filter object may implement the IFWXSlowDataFilter interface to prevent premature termination of a connection.

When a Firewall client application calls the Windows Sockets WSACleanup function, the client DLL will close the Firewall service session. As a result, the Firewall service will terminate all connections that were created in this session.

In rare circumstances, this termination may lead to data loss if the client application relies on TCP/IP for receipt acknowledgement. The connection can be closed after acknowledgment of a packet receipt because the slow connection delays receipt of the remaining packets. This is not a problem if the client application uses application-level acknowledgement.

To prevent data loss in these cases, implement the IFWXSlowDataFilter interface.


Filter Development Process

The filter development process is described here in general terms. For more specific information, review the procedure in How to Create an Application Filter. In describing this process, use of the Visual Studio Active Template Library (ATL) is assumed and recommended, as it handles much routine work for the project.

Application filters typically require these procedures:

  • Create the necessary COM objects Typically, these are the filter object, session filter object, and data filter object.
  • Monitor events
  • Attach the filter to a session
  • Process data
  • Provide code to register and unregister the filter
  • Installation

Note Filters must be registered as COM servers and in the ISA configuration.


Best Practices

The best practices provided here will help you create more efficient application filters.

Registration for Events

  • Register for as small a set of events as possible. This is true for first-phase events registered in IFWXFilter::FilterInit, and for events registered in IFWXFilter::AttachToSession. Unnecessary event registrations increase the load on the Firewall service, and reduce performance.
  • In IFWXFilter::AttachToSession, don't define explicit data filters unless monitoring or modification of the stream is really needed. This allows the Firewall service to do the data pumping in kernel mode, which is more efficient than the user-mode data pumping of data filters.

Buffers and Data

  • Data copy reduces performance, so avoid copying I/O Buffer content. Instead, use the methods of the IFWXIOBuffer interface to manage data buffers. To avoid copying buffers, a filter should call IFWXSocket::Recv, specifying NULL as the buffer. This causes the Firewall service to pass to the filter an existing buffer, instead of copying from the existing buffer to the filter's buffer.

Threading

  • If your filter performs asynchronous I/O on operating-system files, use the completion notification mechanism provided by ISA. For more information, see Completion Notification Objects.
  • Call the IFWXProxy::StartHeavyBlockingOperation method before making a blocking operation. When this method is used the Firewall service keeps track of the number of threads that are busy with blocking operations, and creates new threads when necessary.
  • Do not call IFWXProxy::StartHeavyBlockingOperation before waiting for a critical section or a resource on which other threads are likely to be blocked. If the newly created thread is blocked on the same critical section, there will be greater congestion on the critical section and more context switches, resulting in an overall reduction in performance.
  • Expect methods to be called from different threads simultaneously. If more than one thread accesses data at the same time, the data can be left in an inconsistent state. You can prevent this by using critical sections, which allow only one thread at a time to use the protected code section. Examples of the use of critical sections can be seen in the sample application filters provided with the ISA SDK. For more information on critical sections, see MSDN.
  • Similarly, you can use interlocked functions, which synchronize access to a variable that is shared by multiple threads. Interlocked functions prevent a thread from being preempted when it is in the middle of incrementing or checking a variable. For more information on critical sections, see MSDN.
  • In general, when calling a method of an object that may call back the calling object (either on the same thread or by waiting for another thread to perform the callback), a deadlock may arise. Therefore, avoid holding locks while calling methods of Firewall service-implemented objects.

    For example, there may be a race between calls to Detach (IFWXDataFilter::Detach, or IFWXSessionFilter::Detach) and other methods.Data filters receive IFWXSocket interfaces when the IFWXDataFilter::SetSockets API is called. Because the Firewall service is multithreaded, more than one thread can use the same IFWXSocket interface simultaneously. Furthermore, one thread may call Detach to release the IFWXSocket interface, while the other thread still attempts to access the interface, perhaps while doing a "data-pump". Access to the interface should be protected by a locking mechanism such as a critical section. Because of locking by the Firewall service, deadlock situations may arise; for example, the following code can lead to a "deadlock" situation:

    Lock();
HRESULT hr = spSocket->Close(FALSE);
Unlock();

    To avoid the deadlock, use this code:

    // Copy member pointer to interface to a local "smart" pointer
// while the object is locked
CComPtr<IFWXSocket> spSocket;
Lock();
spSocket = m_InternalSocket;
Unlock();   // lock released to avoid deadlocks

// Must verify that interface was not released by Detach()
if (spSocket != NULL) {
// Here it is safe to send, receive or close the socket.
HRESULT hr = spSocket->Close(FALSE);
}
  • Avoid creating too many threads in the Firewall service. If you create a thread that waits for an infrequent event, such as a configuration change, use the Win32 function RegisterWaitForSingleObject. If you create a thread to perform periodic tasks that will spend most of its time sleeping, use the Win32 function CreateTimerQueueTimer. Each of these functions uses thread pools to reduce the number of threads that are busy at one time.


Application Filter Test Environment

After you've developed an application filter, you will want to test it in a laboratory setting. To do this, configure the lab to represent a network/proxy-server/Internet situation:

Lab Configuration

Three computers are required to test application filters. One computer functions as the ISA server. This computer must have two network interface cards (NICs). Connect one card to a computer representing the internal client and the other to a computer representing the Internet.

The specific lab requirements will depend on the type of filter you are testing. For an example of a specific test setup and procedure, see SMTPFLTR Test Environment.


Filter Setup

You must install filters on the ISA Server computer, where they must reside locally. Filters must be registered as COM servers and in the ISA configuration.

The registration process includes the following steps:

  1. Copying the DLLs and any other necessary files to the ISA Server computer.
  2. Registering the COM objects. The registration is typically implemented in the DllRegisterServer function, which can be activated by the regsvr32 command.
  3. Register the filter in ISA Storage as an application filter for the firewall service using IFWXFilterAdmin::InstallFilter. This step can also be done in the DLLRegisterServer function.
  4. Register the filter protocols, primary connection ports, and alert events, as necessary.

Note Because the filter objects are created when the Firewall service starts, the server must be stopped and then restarted after setup is completed.

The regsvr32 utility is not a required part of the setup. A setup utility can use regsvr32, or load the DLL and call the registration code directly.

Services may not have the necessary permissions to allow them to write vendor-specific information to the DS. For this reason, you should perform the saving of vendor parameters to ISA during filter setup.


Example Code

The code for event registration can be written in the context of the filter registration code. For an example of this, see How to Create an Application Filter.

The code for registering filters and protocols should be written in the FilterName.cpp file.

Registering the Filter Object

//Create the FWXFilterAdmin object
HRESULT ProxyReg()
{
    HRESULT hr;
    IFWXFilterAdmin *ifa = NULL;

    hr = CoCreateInstance(CLSID_FWXFilterAdmin,
                NULL,
                CLSCTX_SERVER,
                IID_IFWXFilterAdmin,
                (void**)&ifa);
    if (FAILED(hr)) return hr;

//Register the class as a filter
    hr = ifa->InstallFilter(CLSID_EBFilter,

                L"Sample filter",
                L"Long description here..",
                L"1.0",
                NULL);
    ifa->Release();

    return hr;
}

Protocol Registration

// HRESULT hr;
// IFWXFilterAdmin *ifa;

hr = ifa->RegisterProtocolForFilter(CLSID_FTPFilter,
                L"FTP",
                L"FTP protocol via ftpfltr filter",
                NULL);


How to Create an Application Filter

This section describes how to create an SMTP application filter, which captures and analyzes data sent by external clients.

A step-by-step example shows you how to create an SMTP filter. In order to simplify the procedure, this particular filter does not have complete SMTP filtering functionality. The filter can search for a particular string, but does not act based on that string. A fully functional SMTP filter is provided with ISA Server, and a sample SMTP filter is provided with the ISA SDK. Comparison of the code in this section with the code in the sample SMTP filter will highlight where the filter functionality code should be placed.

The sample SMTP filter demonstrates the use of a data filter factory, not shown in this step-by-step example.

The example consists of the sequential steps in the following sections:

  • Creating the Filter
  • Attach a Session Filter to a Proxy Session
  • Add Registration Code and Register the Filter
  • Add SMTP Content Filtering Using the IFWXDataFilter Interface
  • Reading Configuration from Vendor Parameter Sets
  • Notifying the ISA Server of Alert Events


Creating the Filter

To follow the procedures in this section, use the Visual C++ Active Template Library (ATL) wizards to create the SMTP filter. In the Integrated Development Environment (IDE) wizard dialogs, use default settings unless otherwise specified. This procedure assumes that the filter classes were not previously registered on the computer where the filter is being built.

This section contains two procedures:

  • Creating the COM Filter Object
  • Creating a Filter Object that Monitors AcceptedConnection Events


Creating the COM Filter Object

To begin developing a application filter, you must create a new project, and then include the necessary header and .idl files. For more information about these declaration files, see Header and .Idl Files Provided with ISA.

To create the COM filter object

  1. Create a new project (using the ATL COM AppWizard) with the following properties:
    • Name — SMTPFLTR
    • Server Type — DLL
  2. Add the header and .idl files to the project:

    In the Project Settings dialog box, select the C/C++ tab, and from the Category drop-down menu select Preprocessor. In the Preprocessor definitions entry field, add the SDK path to the include path of the project. Type the same path information in the Additional include directories entry field of the MIDL tab. Then add wspfwext.idl and msfpccom.idl to the project's source files.

    To include all interface definitions and their GUIDs that are required to build a filter (for example, IFWXFilter, IFWXSessionFilter, or IFWXDataFilter), import wspfwext.idl at the beginning of the SMTPFLTR.idl file:

    import "oaidl.idl";        // line produced by the wizard
import "ocidl.idl";        // line produced by the wizard
import "wspfwext.idl";     // you add this line

    The build process produces other files, such as wspfwext.h and wspfwext_i.c.

  3. Build the project.
  4. Add include statements:

    The header file wspfwext.h contains the definitions of all necessary filter interface methods (IFWXFilter, IFWXSessionFilter, and so forth). Add an include statement for wspfwext.h to the precompiled header file stdafx.h:

    #include "wspfwext.h"

    The MIDL-generated file wspfwext_i.c contains predefined GUIDs for the filter interfaces. Include it in one of the .cpp files, such as SMTPFLTR.cpp.

    #include "wspfwext_i.c"


Creating a Filter Object that Monitors AcceptedConnection Events

You need to create a filter object that will implement the IFWXFilter interface. This interface is necessary for the creation of a filter. The filter object will monitor AcceptedConnection events.

Warning Visual C++ will not create a new ATL object if more than one .idl file is included in your project. Delete all the .idl files except SMTPFLTR.idl from the project, add the ATL object as described in step 1, and then put back in the .idl files that you removed.

To create the filter object

  1. Create a COM object that implements the IFWXFilter interface.

    Insert a new ATL object (Simple Object), with the following properties:

    • Short Name — SMTPFilter
    • Interface — IFWXFilter
    • Attributes:

      Threading Model — Free

      Interface — Custom

      Aggregation — No

  2. Edit the SMTPFLTR.idl file. Because the IFWXFilter interface and its GUID are already defined in wspfwext.idl, you must delete the IFWXFilter-related code that is produced in SMTPFLTR.idl by the wizard:
    [
        uuid(20F10C85-2C5E-11D2-8C3D-006094EB63EF),

        helpstring("IFWXFilter Interface"),
        pointer_default(unique)
]
interface IFWXFilter : IUnknown
{
};
  3. Add declaration of IFWXFilter methods. Use wspfwext.h to get the prototypes of the methods of IFWXFilter and add them to SMTPfilter.h. Note that you must remove virtual, void and =0 from the methods. Insert the following code:
    // IFWXFilter
public:
    HRESULT STDMETHODCALLTYPE FilterInit(
/* [in] */ IFWXProxy __RPC_FAR *pIFWXProxy,
/* [out] */ PFwxFilterHookEvents __RPC_FAR *ppFilterHookEvents);

    HRESULT STDMETHODCALLTYPE FilterShutdown(void);

    HRESULT STDMETHODCALLTYPE AttachToSession(
    /* [in] */ IFWXSession __RPC_FAR *piSession,
    /* [out] */ IFWXSessionFilter __RPC_FAR *__RPC_FAR *piSessionFilter,
    /* [out] */ PFwxFilterHookEvents __RPC_FAR *ppFilterHookEvents);
  4. Add the implementation of IFWXFilter methods. Use wspfwext.h to get the prototypes of the methods of IFWXFilter and add them to SMTPfilter.cpp with implementation code.

    Note When you inserted the ATL object SMTPFilter, Visual C++ created a default implementation of IFWXFilter methods in SMTPFilter.h. The default implementations should be removed from that file.

    Start with a simple implementation; for example,

    return E_NOTIMPL;

    The implementation code should look like this:

    // CSMTPFilter

    HRESULT STDMETHODCALLTYPE CSMTPFilter::FilterInit(
            /* [in] */ IFWXProxy __RPC_FAR *pIFWXProxy,
            /* [out] */ PFwxFilterHookEvents __RPC_FAR *ppFilterHookEvents)
    {
        return E_NOTIMPL;

    }

    HRESULT STDMETHODCALLTYPE CSMTPFilter::FilterShutdown( void)
    {
        return E_NOTIMPL;

    }

    HRESULT STDMETHODCALLTYPE CSMTPFilter::AttachToSession(
        /* [in] */ IFWXSession __RPC_FAR *piSession,
        /* [out] */ IFWXSessionFilter __RPC_FAR *__RPC_FAR *piSessionFilter,
        /* [out] */ PFwxFilterHookEvents __RPC_FAR *ppFilterHookEvents)
    {
        return E_NOTIMPL;

    }
  5. Implement the IFWXFilter::FilterInit method. The Firewall service calls this method on startup. In the IFWXFilter::FilterInit method you will save a reference to the IFWXProxy interface to be used later. Then you will define the set of initial events that the filter will monitor. This example monitors the AcceptedConnection and fwx_Bind_Tcp events. However, for performance reasons it is better to monitor less-common events at the IFWXFilter level. Therefore, your filter will monitor the fwx_Bind_Tcp events for port 25 and when they occur it will also monitor fwx_AcceptedConnection events. You also must define the port from which you want to receive events. In this example the port is 25.

    In SMTPfilter.h, add the following code:

    private:
    CComPtr<IFWXProxy>       m_pIFWXProxy;
    FwxFilterHookEvents      m_FwxFilterHookEvents;
    FwxPortRangeEvents       m_FwxPortRangeEvents;

    In SMTPfilter.h, locate the default object constructor code created by C++:

        CSMTPFilter()
    {
    }

    and replace it with the following object constructor code:

    CSMTPFilter::CSMTPFilter ()
{
    m_FwxPortRangeEvents.StartPort = 25;
    m_FwxPortRangeEvents.EndPort  = 25;
    m_FwxPortRangeEvents.dwSocketEvents =
        FWX_ALL_SOURCES // Event Source is either NAT or Firewall client
        | fwx_Bind_Tcp;//At this level, monitor binds

    m_FwxFilterHookEvents.dwGlobalEvents        = 0;
    m_FwxFilterHookEvents.dwNumPortRanges       = 1;
    m_FwxFilterHookEvents.FwxPortRangeEvents       = &m_FwxPortRangeEvents;
}
  6. Implement the IFWXFilter::FilterShutdown method. This is a request to the filter to shut down. Since this filter doesn't hold a reference to any object except the proxy callback interface, it can simply return S_OK. The implementation should be in SMTPfilter.cpp, in place of the previously inserted implementation of return E_NOTIMPL..
    HRESULT STDMETHODCALLTYPE CSMTPFilter::FilterShutdown( void)
{
    return S_OK;
}
  7. Build the project.


Attach a Session Filter to a Proxy Session

The Firewall service uses IFWXFilter::AttachToSession to inform the filter that an event it is registered for has occurred. The filter then must create an instance of the FWXSessionFilter object that implements the IFWXSessionFilter interface.

This section contains three procedures that you must follow in order to attach a session filter to a proxy session:

  1. Create a COM Object that Implements the IFWXSessionFilter Interface
  2. Implement the IFWXFilter::AttachToSession Method
  3. Add the Definition and Implementation of IFWXSessionFilter Methods


Create a COM Object that Implements the IFWXSessionFilter Interface

In this procedure, you will implement the following methods:

  • IFWXSessionFilter::FwxProxyEventHandler
  • IFWXSessionFilter::Detach

To create the FWXSessionFilter object

In the following steps you will use the ATL Object Wizard to create the skeleton for the new object. Because this object doesn't have to be created outside the filter, you can reduce the size of your code by removing ATL-generated code that supports the CoCreateInstance function or other COM mechanisms to create objects. To avoid having to edit the files that were edited in the case of the IFWXFilter interface, back up the current versions, and restore them after you add the new object:

  1. Make a copy of these files: SMTPFLTR.rc, resource.h and SMTPFLTR.idl
  2. Insert a new ATL object (Object — Simple Object):
    • Short Name — FWXSessionFilter
    • Interface — IFWXSessionFilter
    • Attributes:

      Threading Model — Free

      Interface — Custom

      Aggregation — No

  3. Cleanup:
    • Restore the files: SMTPFLTR.rc, resource.h and SMTPFLTR.idl
    • Delete fwxsessionfilter.rgs and remove it from the project workspace.
    • From smtpfltr.cpp delete the line:
      OBJECT_ENTRY(CLSID_FWXSessionFilter, CFWXSessionFilter)
    • From fwxsessionfilter.h delete the lines
      public CComCoClass<CFWXSessionFilter, &CLSID_FWXSessionFilter>,
    • and
      DECLARE_REGISTRY_RESOURCEID(IDR_FWXSESSIONFILTER)


Implement the IFWXFilter::AttachToSession Method

Although AttachToSession is an IFWXFilter method rather than an IFWXSessionFilter method, it can be implemented only after the FWXSessionFilter object has been created.

The Firewall service calls this method when a registered event of the filter occurs (as defined in FilterInit). The COM method CComObject<>::CreateInstance is similar to the CoCreateInstance function, but only creates an instance of the class (with a reference count equal to 0) and does not need a GUID to do so. Add the following code to SMTPFilter.cpp, in place of the simple implementation you inserted earlier:

HRESULT STDMETHODCALLTYPE CSMTPFilter::AttachToSession(
    /* [in]  */ IFWXSession __RPC_FAR *piSession,
    /* [out] */ IFWXSessionFilter __RPC_FAR *__RPC_FAR *piSessionFilter,
    /* [out] */ PFwxFilterHookEvents __RPC_FAR *ppFilterHookEvents)
{
    OutputDebugString ("FWXFilter::AttachToSession\n");

    HRESULT hr = S_OK;

    CComObject<CFWXSessionFilter> *pSessionFilter;
    CComPtr<IFWXSessionFilter> spIFWXSessionFilter;

    hr = CComObject<CFWXSessionFilter>::CreateInstance (&pSessionFilter);
    if (FAILED(hr))
        return hr;

    pSessionFilter->AddRef();

    hr = pSessionFilter->QueryInterface(IID_IFWXSessionFilter,
                                       reinterpret_cast<void**>(&spIFWXSessionFilter));
    pSessionFilter->Release();

    if(SUCCEEDED(hr))
    {
        //Define new set of events
        m_FwxPortRangeEvents.dwSocketEvents=FWX_ALL_SOURCES
                                         | fwx_AcceptedConnection
                                         | fwx_Bind_Tcp;

        hr = m_pIFWXProxy->DuplicateFilterHookEvents (&m_FwxFilterHookEvents,
                                                     ppFilterHookEvents);
    }
    if (FAILED(hr))
        return hr;

    *piSessionFilter = spIFWXSessionFilter.Detach();
    return hr;
}

Add to smtpfilter.cpp the following include statement:

#include "FWXSessionFilter.h"


Add the Definition and Implementation of IFWXSessionFilter Methods

Now add the code to define and implement the IFWXSessionFilter methods.

To define and implement the IFWXSessionFilter methods

Take the following steps to define and implement the IFWXSessionFilter methods:

  1. Add the IFWXSessionFilter Method definitions:

    Use wspfwext.h to get the prototypes of the methods of IFWXSessionFilter and add them to fwxsessionfilter.h.

    Add the declaration of the methods to fwxsessionfilter.h, in the public section of the CFWXSessionFilter. The code should be:

    HRESULT STDMETHODCALLTYPE FwxProxyEventHandler(
        /* [ref][in] */ FwxProxyEvent __RPC_FAR *pProxyEvent);

    HRESULT STDMETHODCALLTYPE Detach( void);
  2. Add the IFWXSessionFilter method implementations:

    Copy the prototypes of the IFWXSessionFilter methods from wspfwext.h, and add them to fwxsessionfilter.cpp with implementation code.

    Note When you inserted the ATL object SMTPFilter, Visual C++ created a default implementation of IFWXSessionFilter methods in FWXSessionFilter.h. The default implementations should be removed from that file.

    Start with a simple implementation in FWXSessionFilter.cpp; for example,

    return E_NOTIMPL;

    The implementation code should look like this:

    HRESULT STDMETHODCALLTYPE CFWXSessionFilter::FwxProxyEventHandler(
        /* [ref][in] */ FwxProxyEvent __RPC_FAR *pProxyEvent)
{
    return E_NOTIMPL;

}

HRESULT STDMETHODCALLTYPE CFWXSessionFilter::Detach( void)
{
    return E_NOTIMPL;

}
  3. Implement IFWXSessionFilter::FwxProxyEventHandler:

    Add the IFWXSessionFilter::FwxProxyEventHandler implementation to FWXSessionFilter.cpp, in place of the simple implementation:

    HRESULT STDMETHODCALLTYPE CFWXSessionFilter::FwxProxyEventHandler(
    /* [out][in] */ FwxProxyEvent __RPC_FAR *pProxyEvent)
{
    HRESULT hr = S_OK;
    IFWXConnection  *piConnection;

    switch (pProxyEvent->EventType)
    {
    // Bind request for TCP sockets
    case fwx_Bind_Tcp:
        OutputDebugString ("IFWXSessionFilter::FwxProxyEventHandler –
        fwx_Bind_Tcp\n");
        OutputDebugString (FilterAccessString(
                           pProxyEvent->
                           Parameters.Bind.FwxFilterAccess));

        //Get a pointer to the connection
        piConnection=pProxyEvent->Parameters.Bind.piConnection;

        break;

    // Inbound connection on a listening TCP socket
    case fwx_AcceptedConnection:
        OutputDebugString ("IFWXSessionFilter::FwxProxyEventHandler –
                           fwx_AcceptedConnection\n");
        OutputDebugString (FilterAccessString(pProxyEvent->
                           Parameters.Accept.FwxFilterAccess));
        // The code for attaching a data filter that will do the actual
        //work will be placed here.
        break;

// Unexpected EventType
    default:
    OutputDebugString ("Error - FWXSessionFilter::FwxProxyEventHandler
                                    –Unexpected Event Type ");
        return E_FAIL;
    }

    return  hr;
}

    Also, add the FilterAccessString definition to FWXSessionFilter.cpp, immediately after the #include statements, as follows:

    // This function converts enum value to a corresponding string
static const char* FilterAccessString (int FwxFilterAccess)
{
    switch (FwxFilterAccess)
    {
        case FWX_ALLOW:
            return "Filter Access: FWX_ALLOW\n";
        case FWX_DENY:
            return "Filter Access: FWX_DENY\n";
        case FWX_PASS:
            return "Filter Access: FWX_PASS\n";
        case FWX_EMULATE:
            return "Filter Access: FWX_EMULATE\n";
    }
    return "Invalid Filter Access";
}
  4. Implement the IFWXSessionFilter::Detach method, in place of the simple implementation:

    Typically, the IFWXSessionFilter::Detach method is used to release references to other objects that must be released when the session ends. In this case, there are none:

    // Detach should return S_OK
HRESULT STDMETHODCALLTYPE CFWXSessionFilter::Detach( void)
{
    return S_OK;
}
  5. Build the project.


Add Registration Code and Register the Filter

In this section you will follow two steps, first adding the registration code, and then registering the filter. The registration code includes filter and protocol registration.

Filter Registration

Filter object instances are created during the Firewall service startup. The class identifier (CLSID) of a filter must be registered in order for the Firewall service to create it. This usually should be done during the COM server registration process of the filter, in the exported function DllRegisterServer. Similarly, the filter is unregistered during the COM server unregistration process, in the exported function DllUnregisterServer. Filter registration uses the IFWXFilterAdmin::InstallFilter method.

Protocol Registration

You need to manage network traffic through the filter. To do this, define a protocol that your filter will be using and then create a protocol rule to allow that traffic. See the ISA product documentation for more information about protocol rules.

Defining a protocol is done by calling the RegisterProtocolForFilter function. After registering the protocol, you need to add the primary connection definition to the protocol.

Note You only need to define a protocol for Protocol-enabling filters: For more information see Filter Types.


Add the Registration Code

This section describes how to add the registration code to your filter.

To add the registration code

  1. In the Visual C++ Project Settings dialog box, select the C/C++ tab, and from the Category drop-down menu select Preprocessor. In the Preprocessor definitions entry field, add to the include path of the project the appropriate directory for your compilation. This ensures that the compiler can find the msfpccom.tlb file (if the file is not located in a current include directory). Type the same path information in the Additional include directories entry field of the MIDL tab.
  2. In Project Settings, select the C++ tab, and in the C++ Language Category drop-down menu, click Enable Exception Handling.
  3. Add the following code to StdAfx.h, before the #include Wspfwext.h directive:
    #import "msfpccom.tlb" rename_namespace("MSFPCCOM") named_guids
//define the GUID string with your filter GUID value
#define FILTER_GUID_STRING "{7CCF6FF0-D995-4da1-B452-4228047B2D1D}"
//define the FILTER_PROTOCOL_GUID
static const GUID FILTER_PROTOCOL_GUID = { 0x8226e96a, 0xb578, 0x4c28, { 0xb6, 0x86, 0x7e, 0xc9, 0x2b, 0xaf, 0x1e, 0xe7 } };
#define FILTER_PROTOCOL_GUID_STRING "{8226E96A-B578-4c28-B686-7EC92BAF1EE7}"

    In SMTPFltr.cpp, add the following code to your filter registration code:

    // This function is used to register an application filter
static HRESULT RegisterFWXFilter (bool fRegister)
{
    HRESULT hr;
    MSFPCCOM::IFPCFilterProtocolPtr comptrIFPCFilterProtocol;    CComPtr<IFWXFilterAdmin> pIFWXFilterAdmin;

    hr = CoCreateInstance (CLSID_FWXFilterAdmin,
                  NULL,
                  CLSCTX_SERVER,
                  IID_IFWXFilterAdmin,
                  (LPVOID *) &pIFWXFilterAdmin);
    if (FAILED(hr))
        return hr;

    if (fRegister)
    {
        //Strings should be Unicode in this call
        hr = pIFWXFilterAdmin->
        InstallFilter (CLSID_SMTPFilter,// GUID

                      L"SMTPFilter",// Name
                      L"Screen SMTP messages",// Description
                      L"Microsoft",// Vendor
                      L"1.0",// Version
                      NULL);//Reserved parameter, must be NULL

        //OK if already installed.
        if (hr == HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS))

            hr = S_OK;

        try
        {
            hr = pIFWXFilterAdmin
                 ->RegisterProtocolForFilter(CLSID_SMTPFilter,
                                             FILTER_PROTOCOL_GUID,
                                             L"SMTP server",
                                             L"SMTP inbound via SMTPFLTR",
                                             NULL);//Reserved parameter, must be NULL
           // Returns OK if already installed.
           if (hr == HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS))
                hr = S_OK;
           if (FAILED(hr))
                return hr;

        //Get a pointer to the protocol just registered
        hr = pIFWXFilterAdmin->GetProtocol(CLSID_SMTPFilter,
                                    FILTER_PROTOCOL_GUID,
                                    (struct IFPCFilterProtocol **)&comptrIFPCFilterProtocol);

        if (FAILED(hr))
            return hr;

        //Add primary connection to the protocol just created
        comptrIFPCFilterProtocol->PrimaryConnections->Add(MSFPCCOM::fpcInbound,
                                        MSFPCCOM::prxTCP,
                                        25,
                                        25);

        comptrIFPCFilterProtocol->PrimaryConnections->Save();        }
        catch(_com_error& err)
        {
            //If the event already exists, it is not considered an error
            if(err.Error() != HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS))
                return err.Error();
        }

    }
    else
    {
        //Unregister protocol
        hr = pIFWXFilterAdmin->
            UnregisterProtocolForFilter(CLSID_SMTPFilter,
                                        FILTER_PROTOCOL_GUID);
        hr = pIFWXFilterAdmin->UninstallFilter (CLSID_SMTPFilter);
    }
    return hr;
}
  4. In the implementation of IFWXSessionFilter::ProxyEventHandler in SessionFilter.cpp, add the code shown in bold to set the connection protocol as the filter protocol:
            //Get a pointer to the connection
        piConnection=pProxyEvent->Parameters.Bind.piConnection;

        //Set the protocol of this connection to be the filter
        //protocol
        hr = piConnection->SetProtocol(FILTER_PROTOCOL_GUID,0);

        if (FAILED(hr))
        {
            OutputDebugString("\tFail to set protocol of connection to
                                            SMTP filter protocol\n");
            return hr;
        }

        break;


Register the Filter

After you've added the registration code, register the filter.

To register the filter

  1. Call this function as appropriate in DllRegisterServer and DllUnregisterServer exported functions (in place of the default DllRegisterServer and DllUnregisterServer functions):
    STDAPI DllRegisterServer(void)
{
    // registers object, typelib and all interfaces in typelib
    HRESULT hr = _Module.RegisterServer(TRUE);
    if (SUCCEEDED(hr))
    {
        hr = RegisterFWXFilter (true);
        if (FAILED(hr))
            _Module.UnregisterServer(TRUE);
    }
    return  hr;
}

STDAPI DllUnregisterServer(void)
{
    RegisterFWXFilter (false);
    return _Module.UnregisterServer(TRUE);
}
  2. Filter objects are created when the Firewall service is loaded, so the service must be stopped and then restarted to add a new filter or a new version of an existing filter.

    Stop the Firewall service.

  3. COM registration

    To install the filter, type this line at the command prompt:

    regsvr32 SMTPFLTR.dll

    To remove the filter, type this line at the command prompt:

    regsvr32 /u SMTPFLTR.dll.
  4. Start the Firewall service.


Add SMTP Content Filtering Using the IFWXDataFilter Interface

The data filter in this example will look for a string (configurable) in the SMTP message. The proxy will attach a new instance of the data filter to every inbound TCP connection to Port 25 (monitoring the fwx_AcceptedConnection event on this port).

You will need to take the following steps:

  1. Create a COM Object that Implements the IFWXDataFilter Interface
  2. Add the Definition and Implementation of IFWXDataFilter Methods
  3. Attach the data filter
  4. Implement the IFWXIOCompletion Interface
  5. Implement the _CloseSockets and _GetSockets Functions
  6. Perform Data Pumping


Create a COM Object that Implements the IFWXDataFilter Interface

When you create the data filter object, you will implement the following methods:

  • IFWXDataFilter::SetSockets
  • IFWXDataFilter::Detach
  1. Follow cleanup steps similar to those taken to create the COM object that implemented IFWXSessionFilter.
  2. Insert a new ATL object (Object — Simple Object)
    • Short Name — SMTPDataFilter
    • Interface — IFWXDataFilter
    • Attributes:

      Threading Model — Free

      Interface — Custom

      Aggregation — No


Add the Definition and Implementation of IFWXDataFilter Methods

Now add the code to define and implement the IFWXDataFilter methods.

To define and implement the IFWXDataFilter methods

  1. Add the definition of IFWXDataFilter methods:

    Copy the prototypes of the methods of IFWXDataFilter from wspfwext.h and add them to smtpdatafilter.h.

    Add the declaration of the methods to smtpdatafilter.h.     2.    Add the Implementation of IFWXDataFilter Methods

    Use wspfwext.h to get the prototypes of the methods of IFWXDataFilter and add them to SMTPDataFilter.cpp with implementation code.

    Note When you inserted the ATL object SMTPDataFilter, Visual C++ created a default implementation of IFWXFilter methods in SMTPDataFilter.h. The default implementations should be removed from that file.

    Start with a simple implementation in SMTPDatafilter.cpp; for example,

    return E_NOTIMPL;

    The implementation code should look like this:


Attach the Data Filter

In this procedure you will attach a data filter in CSessionFilter::ProxyEventHandler.

To Attach the data filter

  1. Add code, in order for a data filter to be attached to the session when an accept event occurs.
  2. At the beginning of FWXSessionFilter.cpp, add:
    #include "SMTPDataFilter.h"
CComPtr <IFWXDataFilter> spIFWXDataFilter;
  3. In FWXSessionFilter.cpp, in the switch statement of the ProxyEventHandler method, add this code to the fwx_AcceptedConnection case:
    CComObject<CSMTPDataFilter> *pSMTPDataFilter;
//Create an instance of the SMTPDataFilter
hr = CComObject<CSMTPDataFilter>::CreateInstance(&pSMTPDataFilter);
    if (SUCCEEDED(hr))
    {
        pSMTPDataFilter->AddRef();

        hr = pSMTPDataFilter->
QueryInterface(IID_IFWXDataFilter,
             reinterpret_cast<void**>(&spIFWXDataFilter));

pSMTPDataFilter->Release();

        if (FAILED(hr))
        {
            OutputDebugString("\tFail to init DataFilter\n");
            return hr;
        }

        //Attach the data filter to the connection
        piConnection=pProxyEvent->
Parameters.Accept.piConnectionAccepted;
        hr=piConnection->
AttachDataFilter(spIFWXDataFilter,
             fwx_dfpc_External,
             NULL);
    }
  4. Implement the IFWXDataFilter::SetSockets method.

    In order for the data filter to create a data pump — moving data between the internal SMTP server and the external server/client — the data filter must keep a reference to the sockets at each end of the connection. Add the following code to SMTPDataFilter.h:

    private:
    CComPtr<IFWXSocket> m_spExternalSocket;
    CComPtr<IFWXSocket> m_spInternalSocket;

    The Firewall service passes a reference to the external and internal sockets used in this connection and the IFWXDataFilter::SetSockets method starts the data-pumping process. The filter must reserve a reference to these sockets.

    Due to the multithreaded architecture of the Firewall service, access to members must be synchronized. In particular, access to the socket interfaces must be synchronized because they are changed by IFWXDataFilter::Detach (see Step 2, following).

  5. Implement the IFWXDataFilter::SetSockets method.

    In place of the simple implementation code you previously wrote, use the following code in SMTPDataFilter.cpp:

    HRESULT STDMETHODCALLTYPE CSMTPDataFilter::SetSockets(
    /* [in] */ IFWXSocket __RPC_FAR *piInternalSocket,
    /* [in] */ IFWXSocket __RPC_FAR *piExternalSocket,
    /* [in] */ IFWXConnection __RPC_FAR *piConnection,
    /* [unique][in] */ IUnknown __RPC_FAR *punkFilterContext)
    {
        //Keep a reference to the sockets
        Lock();
        m_spExternalSocket = piExternalSocket;
        m_spInternalSocket = piInternalSocket;
        Unlock();

        return S_OK;
    }
  6. Implement the IFWXDataFilter::Detach method.

    The Firewall service calls this method when the data filter is no longer needed. IFWXDataFilter::Detach must release the references to the sockets because they are not valid after this method returns.

    In place of the simple implementation code you previously wrote, use the following code in SMTPDataFilter.cpp:

    HRESULT STDMETHODCALLTYPE CSMTPDataFilter::Detach( void)
    {
        //
        // Dereference sockets.
        //
            Lock();
        m_spExternalSocket = NULL;
        m_spInternalSocket = NULL;
            Unlock();

        return S_OK;
    }
  7. Build the project.


Implement the IFWXIOCompletion Interface

To carry out data pumping, the data filter must use an asynchronous input/output (I/O) method. To do so, the data filter has to implement the IFWXIOCompletion interface. Using this interface, the Firewall service notifies the filter upon completion of an I/O operation.

You will implement the IFWXIOCompletion::CompleteAsyncIO method.

To the CSMTPDataFilter class definition in SmtpDataFilter.h, add inheritance from the IFWXIOCompletion class:

public IFWXIOCompletion

Also, add COM interface support for this interface by adding the following line to the COM map of the CSMTPDataFilter class:

COM_INTERFACE_ENTRY(IFWXIOCompletion)

Copy the prototypes of the IOCompletion::CompleteAsyncIO method from wspfwext.h and add them to SMTPDataFilter.h and SMTPDataFilter.cpp (with a simple implementation):

SMTPDataFilter.h:

//IFWXIOCompletion

public:
    HRESULT STDMETHODCALLTYPE CompleteAsyncIO(
            /* [in] */ BOOL fSuccess,
            /* [in] */ DWORD Win32ErrorCode,
            /* [in] */ IFWXIOBuffer __RPC_FAR *pIOBuffer,
            /* [in] */ UserContextType UserData,
            /* [unique][in] */ LPSOCKADDR ExternalAddress,
            /* [in] */ INT ExternalAddressLength) ;

SMTPDataFilter.cpp:

HRESULT STDMETHODCALLTYPE CSMTPDataFilter::CompleteAsyncIO(
        /* [in] */ BOOL fSuccess,
        /* [in] */ DWORD Win32ErrorCode,
        /* [in] */ IFWXIOBuffer __RPC_FAR *pIOBuffer,
        /* [in] */ UserContextType UserData,
        /* [unique][in] */ LPSOCKADDR ExternalAddress,
        /* [in] */ INT ExternalAddressLength)
    {
       return S_OK;
    }

This method is called when an I/O operation is completed. In this method you should implement the logic of your filter. This logic is based on the protocol in which you are working; in this case, the SMTP protocol. To start the data pump, add the code shown in bold to CSMTPDataFilter::SetSockets (in SMTPDataFilter.cpp):

HRESULT STDMETHODCALLTYPE CSMTPDataFilter::SetSockets(
    /* [in] */ IFWXSocket __RPC_FAR *piInternalSocket,
    /* [in] */ IFWXSocket __RPC_FAR *piExternalSocket,
    /* [in] */ IFWXConnection __RPC_FAR *piConnection,
    /* [unique][in] */ IUnknown __RPC_FAR *punkFilterContext)

    {
        //Keep a reference to the sockets
        Lock();
        m_spExternalSocket = piExternalSocket;
        m_spInternalSocket = piInternalSocket;
        Unlock();
    //SOURCE_IS_SERVER and SOURCE_IS_CLIENT are used
    //to differentiate between recv on external and internal sockets
    #define SOURCE_IS_SERVER 0
    #define SOURCE_IS_CLIENT 1
    piInternalSocket ->Recv(NULL,this, SOURCE_IS_SERVER);
    piExternalSocket ->Recv(NULL,this, SOURCE_IS_CLIENT);
        return S_OK;
    }


Implement _CloseSockets and _GetSockets Functions

The function _CloseSockets is used by the data pump in the step Perform Data Pumping; _CloseSockets requires the function _GetSockets.

Implement _CloseSockets in SMTPDataFilter.cpp:

void CSMTPDataFilter::_CloseSockets(BOOL fAbortive)
    {
        CComPtr <IFWXSocket> spExternalSocket;
        CComPtr <IFWXSocket> spInternalSocket;

        OutputDebugString("\tCSMTPDataFilter::_CloseSockets\n");

        _GetSockets(&spInternalSocket,&spExternalSocket);

        if (spInternalSocket)
                    spInternalSocket->Close(fAbortive);

        spInternalSocket.Release();

        if (spExternalSocket)
                    spExternalSocket->Close(fAbortive);

        spExternalSocket.Release();
    }

Add the definition of the _CloseSockets function

void CSMTPDataFilter::_CloseSockets(BOOL fAbortive)

to the header file SMTPDataFilter.h in the private portion of the CSMTPDataFilter class.

Add the function _GetSockets to SMTPDataFilter.cpp:

    void CSMTPDataFilter::_GetSockets(IFWXSocket **ppInternalSocket,
                    IFWXSocket **ppExternalSocket)
    {
            Lock();

            //Get internal socket
           *ppInternalSocket= m_spInternalSocket;
            if (*ppInternalSocket)
        (*ppInternalSocket)->AddRef();

            //Get external socket
           *ppExternalSocket= m_spExternalSocket;
            if (*ppExternalSocket)
        (*ppExternalSocket)->AddRef();

            Unlock();
    }

Add the definition of the _GetSockets function

void CSMTPDataFilter::_GetSockets(IFWXSocket **ppInternalSocket,
                    IFWXSocket **ppExternalSocket)

to the header file SMTPDataFilter.h in the private portion of the CSMTPDataFilter class.


Perform Data Pumping

This example uses a simple data pump that moves data between the server and the client. The actual SMTP filter code uses more sophisticated data pumping and filtering. See SMTPFLTR for more information.

The _CloseSockets function defined in the stepImplement _CloseSockets and _GetSockets Functions is used here.

Add the following code in SMTPDataFilter.cpp in place of the simple implementation of CSMTPDataFilter::CompleteAsyncIO:

HRESULT STDMETHODCALLTYPE CSMTPDataFilter::CompleteAsyncIO(
    BOOL      fSuccess,
    DWORD     Win32ErrorCode,
    IFWXIOBuffer *pIOBuffer,
    UserContextType     UserData,
    PSOCKADDR From,
    INT       FromLen
    )
{
    DWORD DataLength = 0;
    char *pchCurrent;

    //If the buffer exists, get a reference to it and get its size
    if (pIOBuffer)
        pIOBuffer->GetBufferAndSize((PBYTE*)&pchCurrent, &DataLength);

    //No data was sent, close the sockets
    if (DataLength == 0 || !fSuccess)
    {
        _CloseSockets(!fSuccess);
        return S_OK;
    }

    Lock();
    CComPtr<IFWXSocket>    spExternalSocket = m_spExternalSocket;
    CComPtr<IFWXSocket>    spInternalSocket = m_spInternalSocket;
    Unlock();

    if (UserContextType==SOURCE_IS_SERVER)
    {
        //Source of the data is the server; filter needs to send
        //it to the external client
        spExternalSocket->Send(pIOBuffer,NULL,0);
        //Read from internal SMTP server
        spInternalSocket ->Recv(NULL,this,SOURCE_IS_SERVER);
    }
    else
    {
        //Source of the data is the client, filter needs to send
        //it to the server
        spInternalSocket ->Send(pIOBuffer,NULL,0);

        //Read from client
        spExternalSocket ->Recv(NULL,this,SOURCE_IS_CLIENT);
    }
return S_OK
}


Reading Configuration from Vendor Parameter Sets

To make the filter configurable with respect to changing the string it seeks, you need storage that the filter and the administrator can access to read and write configuration data. This kind of storage is provided by ISA administration COM objects — specifically, the FPCVendorParametersSet object. When you use FPCVendorParametersSet, configuration backup and restore operations are done automatically, together with the rest of the ISA configuration information. FPCVendorParametersSet also allows for the configuration data to be shared across an array

To read configuration from vendor parameter sets

  1. Add a public method in the second-phase construction for the CSMTPDataFilter class. This step is required to pass information to the data filter object. The public method is Initialize, which you should add to the CSMTPDataFilter class in CSMTPDataFilter.h:
        HRESULT Initialize(CComPtr<IFWXProxy> pCallback);

    This initialization method would be called by the CFWXSessionFilter::FwxProxyEventHandler method.

  2. Add a private member to CSMTPDataFilter class in CSMTPDataFilter.h:
    char *m_StringToLookFor;
  3. Add the following code to SMTPDataFilter.cpp:
    HRESULT CSMTPDataFilter::Initialize(CComPtr<IFWXProxy> pCallback)
{

    HRESULT hr=S_OK;
    _bstr_t Value;  //Value from ISA storage
    CComPtr<IFWXFilterAdmin> pIFWXFilterAdmin;
    MSFPCCOM::IFPCVendorParametersSetPtr comptrIFPCVendorParametersSet;
    struct IFPCVendorParametersSet * pIFPCVendorParametersSet;

    hr = CoCreateInstance (CLSID_FWXFilterAdmin,
                           NULL,
                           CLSCTX_SERVER,
                           IID_IFWXFilterAdmin,
                           (LPVOID *) &pIFWXFilterAdmin);
    if (FAILED(hr))
        return hr;

    hr =pIFWXFilterAdmin->GetFilterParameterSet(CLSID_SMTPFilter,&pIFPCVendorParametersSet);
    if (FAILED(hr))
        return hr;

    comptrIFPCVendorParametersSet.Attach((MSFPCCOM::IFPCVendorParametersSet*) pIFPCVendorParametersSet, true);

    try
    {
        //Read the string to find
Value=comptrIFPCVendorParametersSet->Value[_bstr_t("StringValue")];
        m_StringToLookFor =new char [strlen(Value)+1];
        if (m_StringToLookFor ==NULL)
            return E_OUTOFMEMORY;
        strcpy(m_StringToLookFor,Value);
    }
    catch(_com_error& err)
    {
        //Set default value to m_StringToLookFor
        m_StringToLookFor = new char[12];
        strcpy(m_StringToLookFor,"Virus Virus");
    }
    return  S_OK;
}
  4. In SMTPDataFilter.h, add the following code to the default constructor of class CSMTPDataFilter:
    m_StringToLookFor = NULL;

    and add the following destructor of class CSMTPDataFilter:

        ~CSMTPDataFilter()
    {
        delete [] m_StringToLookFor;
    }


Notifying the ISA Server of Alert Events

To inform the system administrator that it found a message containing a string it was seeking, the filter must use an event-raising mechanism. This requires the filter to define an alert event and make the alert event available to the administrator through the filter registration process.

To create an alert event

  1. Register alert events in ISA.

    The filter must define an alert event, which it will signal whenever a string is found. This should not be confused with a proxy event. For information on alerts, see Adding a Custom Event and Alert.

    Definition of the alert event should take place during registration of the filter with the Firewall service, because you want the administrator to be able to define alerts using this event. When the filter is unregistered, it should remove this event definition.

    Add the following code to SMTPFLTR.cpp:

    #define FILTER_DESCRIPTION_STRING "SMTP Filter Event"
#define SMTP_FILTER_DESCRIPTION_STRING "SMTP Filter Event"

    Add the following code to the function RegisterFWXFilter in SMTPFLTR.cpp:

    MSFPCCOM::IFPCPtr comptrIFPC;
MSFPCCOM::IFPCEventDefinitionPtr  comptrIFPCEventDefinition;
//Create an instance of ISA admin object
comptrIFPC.CreateInstance(MSFPCCOM::CLSID_FPC);

    The following should be added to the registration code in the try-catch block:

    try
{
//Create a new event for this filter. The reason this
//code is inside a try-catch block is that if this event
//already exists, an exception will be raised
comptrIFPCEventDefinition =
    comptrIFPC->Arrays->CurrentArray()->
    Schema->EventDefinitionSet
    ->Add(FILTER_DESCRIPTION_STRING,_bstr_t(FILTER_GUID_STRING),NULL);
comptrIFPCEventDefinition->Description = FILTER_DESCRIPTION_STRING;
comptrIFPCEventDefinition->Name = FILTER_DESCRIPTION_STRING;
comptrIFPCEventDefinition->Save(NULL);
}
catch(_com_error& err)
{
    //If the event already exists, it is not considered an error
    if(err.Error() != HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS))
        return err.Error();
}

    The following should be added to the unregistration code of the RegisterFWXFilter function:

    //Remove the event
comptrIFPC->Arrays->CurrentArray()->Schema->EventDefinitionSet->Remove(FILTER_GUID_STRING);
//Save the change
comptrIFPC->Arrays->CurrentArray()->Schema->EventDefinitionSet->Save(NULL);
  2. Create an alert that uses the SMTP event

    See the ISA product documentation for help in creating a new alert.

  3. Signal event when the string is found

    To raise an event the filter must use the alert service API.

    1. Add the file alertsrv.idl to the project; then add the following code to Stdafx.h:
      #import "alertsrv.tlb" rename_namespace("ALERTSRVLib") named_guids
    2. Add a private member to CSMTPDataFilter class in SMTPDataFilter.h:
      ALERTSRVLib::IFPCAlertNotificationPtr m_comptrIFPCAlertNotification;
    3. Add the following code to the CSMTPDataFilter::Initialize function in SMTPDataFilter.cpp:
      hr=m_comptrIFPCAlertNotification.CreateInstance(ALERTSRVLib::IFPCAlertNotificationPtr m_spIFPCAlertNotification);

    Now the filter can call the IFPCAlertNotification::SignalEvent method of this object to signal when the event occurs.


SMTPFLTR Test Environment

The purpose of the SMTPFLTR filter is to screen incoming Simple Mail Transfer Protocol (SMTP) messages. The filter will look for a specified string in the data section of an e-mail message. If the string is found, the filter will signal an ISA event. In addition, it will add a text string to the beginning of the Subject: line in the e-mail message.

Both strings are read from the FPCVendorParametersSet object, making them configurable by the ISA administrator.

This document shows how to test the filter in two real-life scenarios:

  • Incoming SMTP message from an external SMTP client.
  • Incoming SMTP message from an external SMTP server (which is forwarding a request from a different SMTP client).

More information on the SMTP protocol definitions can be found in RFC 821 and RFC 1830.

Note The procedures presented here refer to the use of a Microsoft mail server. If you are using a different mail server, refer to its accompanying documentation for configuration information.

Shell commands provided in this example are for demonstration purposes, and can vary from system to system.


Lab Configuration for SMTPFLTR

This section contains the following topics:

  • ISA Server
  • Internal SMTP Server
  • External SMTP Server


ISA Server

  1. Install Windows 2000 Server.
  2. Install ISA Server.
  3. In the Access Policy|Protocol Rules node of the ISA Console Tree, right-click to select New|Rule, which will start the Protocol Rule Creation Wizard. In the wizard, use the following:
    • Protocol rule action—select Allow the request.
    • Protocol definitions—select Specified protocols.
    • Protocols—select the appropriate protocol from the list. In the case of the SMTP filter, select SMTP(server).
    • Schedule—Always (default).
    • Client Type—Any user, group, or client computer (default).
  4. Stop SMTP service on the ISA computer at the command prompt by typing:
    net stop "Microsoft SMTP Service"


Internal SMTP Server

  1. Install SMTP server.

    Microsoft SMTP server comes with Internet Information Services (IIS) 5.0, which is part of the default installation of Windows 2000 Server.

  2. Install ISA client on the SMTP server. Since the SMTP server is behind the ISA server, it functions as a client in this scenario.

    Use the MSEClnt installation share on the ISA server.

  3. Set up the SMTP server to work behind ISA server.

    Add a text file called wspcfg.ini with the following content in the winnt\system32\inetsrv directory, and then restart IIS:

    [inetinfo]
ServerBindTcpPorts=25
KillOldSession=1
Persistent=1
  4. Restart the SMTP service.
  5. Notice that inetinfo.exe hosts many services. You must stop each service before inetinfo.exe terminates. If you are using SMTP service, you can use the following shell commands:
    net stop "World Wide Web Publishing Service"
net stop "FTP publishing service
net stop "Simple Mail Transport Protocol (SMTP)"
net stop "IIS Admin Service"
net start "Microsoft SMTP Service"

Note When you switch from a Firewall client test configuration to a SecureNAT client test configuration, or from a SecureNAT client to a Firewall client, the Firewall service and the SMTP service must be stopped and restarted.


External SMTP Server

  1. Install SMTP server.
  2. Configure the SMTP service to forward messages:
    • Add new remote domain.
    • Open properties dialog of the new domain.
    • Select the Allow incoming mail to be relayed check box
    • Select the Forward all mail to smart host radio button and type the external name or IP address of the ISA server. Alternatively, use the Smart host setting on the Delivery Property page of SMTP server properties.


Verification

  1. Open the telnet application on the external computer and connect to the ISA server on Port 25.
  2. You should receive a message similar to the following:
    "220 <YourInternalServerName> Microsoft ESMTP MAIL Service, Version: 5.0.2054.0054.0 ready at Mon, 28 Jun 1999 14:10:48 +0300"

This is an indication that the internal SMTP server is available and can be accessed from the external network through ISA. Notice that the server name in this message is that of the internal server, not the ISA server.

If you get an error message, try restarting the Firewall service and then restarting the internal SMTP service.


Sample Filters

Sample application filters developed using the ISA Server SDK are provided in the Samples\application_filters directory on the ISA CD-ROM in the SDK directory. These are provided in order to demonstrate coding techniques for creating application filters. The samples are briefly described below. For more information regarding each filter, see the ReadMe file provided with each sample.

Note to C++ Programmers The samples will work only if compiled using Visual C++ 6.0 with Active Template Library (ATL) 3.0.

CL.EXE, LINK.EXE, and other command-line tools require you to set certain environment variables properly. These include PATH, which must point to the \bin subdirectory of your Visual C++ installation, LIB, which must point to \lib, and INCLUDE, which must point to \include.

When you install Visual C++, Setup creates a batch file, VCVARS32.BAT, containing commands to modify the PATH, LIB, and INCLUDE environment variables. If these variables haven't been set properly, run VCVARS32.BAT before you compile at the command prompt. VCVARS32.BAT is located in the \bin subdirectory. Note that you do not need to run VCVARS32.BAT if you are compiling your program inside the development environment.

For more information, see MSDN.

In addition to the samples, several filters are provided as part of ISA. The functionality of these application filters may also be of interest to filter developers. The filters include:

  • An FTP filter that works with Firewall service and NAT clients.
  • An H.323 protocol filter that works with Firewall service and NAT clients.
  • An HTTP filter.
  • A streaming media filter.

For a general understanding of the filter development process, see Developing Application Filters. For a detailed example of the filter-development procedure, see How to Create an Application Filter.


Connector

The Connector sample is a console application that emulates an application protocol with a primary connection for control, and secondary connections for data. The secondary connections can be inbound or outbound, and use either UDP or TCP.

The Connector application implements both the client and the server side of the protocol.

The related sample filter ConnectorFilter demonstrates how to enable this type of protocol to pass through the Firewall service for Firewall service clients and SecureNAT clients.

A figure illustrating the logic of the Connector and ConnectorFilter samples is provided in ConnectorFilter.


ConnectorFilter

The ConnectorFilter sample filter enables a complex protocol that requires secondary connections on random ports.

The ConnectorFilter sample filter allows the Connector sample to work with SecureNAT clients and Firewall clients.

This figure illustrates the logic of the Connector and ConnectorFilter sample filters.

Methods Used in ConnectorFilter Sample

The ConnectorFilter sample uses the following methods:

IFWXConnection::AttachDataFilter

IFWXConnection::GetExternalSocketName

IFWXIOBuffer::Append

IFWXIOBuffer::GetBufferAndSize

IFWXIOCompletion::CompleteAsyncIO

IFWXProxyAction::Cancel

IFWXSession::AllowFutureConnect

IFWXSession::BindForClient

IFWXSession::GetSessionFlags

IFWXSession::RetroactiveAllowBind

IFWXSessionFilter::Detach

IFWXSessionFilter::FwxProxyEventHandler

IFWXSocket::Close

IFWXSocket::Recv

IFWXSocket::Send

IFWXDataFilter::Detach

IFWXDataFilter::SetSockets

IFWXFilter::AttachToSession

IFWXFilter::FilterInit

IFWXFilter::FilterShutdown

IFWXFilterAdmin::GetProtocol

IFWXFilterAdmin::InstallFilter

IFWXFilterAdmin::RegisterProtocolForFilter

IFWXFilterAdmin::UninstallFilter

IFWXProxy::CreateBuffer

IFWXProxy::DuplicateFilterHookEvents

See Also

Connector


DbgDump

This DbgDump sample filter registers for notifications on all possible events, and installs data filters on all connections. The filter will output information about the events to the debugger.

To view the output, attach a debugger to the fwsrv.exe process. You can also view the output using the DBWIN or DBMON utilities.

Note that because the filter dumps each buffer to the debugger, the Firewall service will experience a considerable slow down and may experience time-outs even with moderate load.

Methods Used in DbgDump Sample

The DbgDump sample uses the following methods:

IFWXConnection::AttachDataFilter

IFWXIOBuffer::GetBufferAndSize

IFWXIOCompletion::CompleteAsyncIO

IFWXSession::GetClientAddress

IFWXSession::GetClientMachineName

IFWXSessionFilter::Detach

IFWXSessionFilter::FwxProxyEventHandler

IFWXSocket::Recv

IFWXSocket::Send

IFWXSocket::SendTo

IFWXSocket::Shutdown

IFWXDataFilter::Detach

IFWXDataFilter::SetSockets

IFWXFilter::AttachToSession

IFWXFilter::FilterInit

IFWXFilter::FilterShutdown

IFWXFilterAdmin::InstallFilter

IFWXFilterAdmin::UninstallFilter

IFWXProxy::DuplicateFilterHookEvents


ExeBlock

The ExeBlock sample filter demonstrates the use of data filters and hooking into the Firewall service thread pool. The filter hooks into FTP control channel (TCP port 21). The data filter (CEBFTPDataFilter) records PORT and PASV commands, and calls the IFWXSession::SetDataFilterFactory method.

When a new secondary connection is made, or accepted, the COM object ClassFactory will create a data filter (CEBScannerDataFilter) that will be attached by the Firewall service. The filter scans the incoming file.

This sample will block all executable files (any file that begins with MZ or ZM) unless a protocol rule is defined allowing a specific user to receive executable files. The user must be defined by an Internet Protocol (IP) address in the case of a Secure NAT client, and by user name in the case of a Firewall client.

The protocol rule must be added to the Protocol Rules in the ISA console.

The scanner data filter creates a temporary file, and downloads the whole file. It then scans the file, and if the file passes, it is transferred to the internal client.

Limitations:

  • The sample does not handle file uploads.
  • The sample does not handle transfer mode different than stream.
  • The sample does not handle structure other than file.

Methods Used in ExeBlock Sample

The ExeBlock sample uses the following methods:

IFWXConnection::AttachDataFilter

IFWXConnection::Deny

IFWXExternalIOCompletion::CompleteAsyncIO

IFWXIOBuffer::Append

IFWXIOBuffer::GetBufferAndSize

IFWXIOBuffer::SetDataSize

IFWXIOCompletion::CompleteAsyncIO

IFWXOverlapped::GetOverlapped

IFWXOverlapped::SetNotificationInterface

IFWXSession::AccessCheck

IFWXSession::SetDataFilterFactory

IFWXSessionFilter::Detach

IFWXSessionFilter::FwxProxyEventHandler

IFWXSocket::Close

IFWXSocket::Recv

IFWXSocket::Send

IFWXDataFilter::Detach

IFWXDataFilter::SetSockets

IFWXFilter::AttachToSession

IFWXFilter::FilterInit

IFWXFilter::FilterShutdown

IFWXFilterAdmin::InstallFilter

IFWXFilterAdmin::RegisterProtocolForFilter

IFWXFilterAdmin::UninstallFilter

IFWXProxy::CreateBuffer

IFWXProxy::CreateConstBuffer

IFWXProxy::CreateOverlapped

IFWXProxy::DuplicateFilterHookEvents

IFWXProxy::HookToCompletionPort


ServerSplit

The ServerSplit sample filter demonstrates the use of connection emulation for inbound connections.

The filter begins by binding a socket for TCP Port 3333, and waiting for connections on this port. When a Firewall client requests to bind Port 3333 on the Firewall service, the filter intercepts the request, and requests to emulate the connection. That is, the service does not attempt to bind a socket to that port in response to that specific client request, because such an attempt would fail if more than one client tries to bind to the same port. Instead, the service reports a successful bind to the client. The filter then manages the multiplexing of incoming connections on the socket that was already bound by the filter.

This technique allows internal servers behind the Firewall service to share listening ports and receive incoming connections from external clients.When a connection arrives to the Firewall service on Port 3333 the service notifies the filter by calling the IFWXAcceptCompletion::CompleteAsyncAccept method. The filter then checks its list of emulated connections. If the list is empty, it sends a short message and terminates the connection. Otherwise, it takes the first connection on the list and calls IFWXConnection::EmulateConnection. The class CDataPump provides the data-pump for this connection. That connection is then moved to the end of the queue.

The following figure summarizes the process followed by the ServerSplit sample.

Note When the external client disconnects, a fwx_ConnectionTerminating event arrives for the accepted connection, but not for the listening connection, if an appropriate ServerBindTcpPorts entry is specified in wspcfg.ini.

Methods Used in ServerSplit Sample

The ServerSplit sample uses the following methods:

IFWXConnection::Deny

IFWXConnection::EmulateConnection

IFWXConnection::SetProtocol

IFWXConnection::SetSocketName

IFWXIOBuffer::GetBufferAndSize

IFWXNetworkSocket::Accept

IFWXNetworkSocket::Bind

IFWXNetworkSocket::Listen

IFWXSessionFilter::FwxProxyEventHandler

IFWXSocket::Close

IFWXSocket::Recv

IFWXSocket::Send

IFWXSocket::SendTo

IFWXSocket::Shutdown

IFWXDataFilter::SetSockets

IFWXFilter::AttachToSession

IFWXFilter::FilterInit

IFWXFilter::FilterShutdown

IFWXFilterAdmin::InstallFilter

IFWXFilterAdmin::RegisterProtocolForFilter

IFWXFilterAdmin::UninstallFilter

IFWXProxy::CreateConstBuffer

IFWXProxy::CreateNetworkSocket

IFWXProxy::DuplicateFilterHookEvents


SMTPFLTR

The SMTPFLTR filter captures and analyzes data sent by external clients using the SMTP protocol. The Firewall service attaches a new instance of the data filter to every inbound port 25 TCP session. The filter can be configured to look for a particular string in the SMTP message.

SMTPFLTR extends the firewall so that it secures SecureNAT clients, which do not have the Firewall client installed.

Note In a SecureNAT scenario, IFWXFilter::AttachToSession and IFWXSessionFilter::FwxProxyEventHandler are not called, due to this filter's use of a class factory to create data filters.

SMTPFLTR is the example used in How to Create an Application Filter.

SMTPFLTR also creates a property sheet for thea application filter, to extend the Microsoft Management Console (MMC). This procedure is described in How to Create a Microsoft Management Console Snap-in.

Methods used in SMTPFLTR sample

The SMTPFLTR sample uses the following methods:

IFWXConnection::SetProtocol

IFWXIOBuffer::GetBufferAndSize

IFWXIOCompletion::CompleteAsyncIO

IFWXSession::BindForClient

IFWXSessionFilter::Detach

IFWXSessionFilter::FwxProxyEventHandler

IFWXSocket::Close

IFWXSocket::Recv

IFWXSocket::Send

IFWXDataFilter::Detach

IFWXDataFilter::SetSockets

IFWXFilter::AttachToSession

IFWXFilter::FilterInit

IFWXFilter::FilterShutdown

IFWXFilterAdmin::GetFilterParameterSet

IFWXFilterAdmin::GetProtocol

IFWXFilterAdmin::InstallFilter

IFWXFilterAdmin::RegisterProtocolForFilter

IFWXFilterAdmin::UninstallFilter

IFWXFilterAdmin::UnregisterProtocolForFilter

IFWXProxy::DuplicateFilterHookEvents

IFWXProxy::GetNATSession


SOCKS Sample Filters

Two SOCKS protocol filter samples are provided with the ISA SDK. One works with the SOCKS 4/4a protocol, and the other with the SOCKS 5 protocol.


SOCKS 4/4a Sample Filter

This sample application filter demonstrates the use of SOCKS protocol version 4/4A. The filter hooks into the SOCKS control channel (TCP port 1080). For each connection made to this port, an object (CSocksConnection) is created. This object identifies calls to IFWXNetworkSocket::Connect and IFWXNetworkSocket::Bind and handles them.

When the CSocksConnection object detects a call to IFWXNetworkSocket::Connect, the filter creates a session for the client's IP address if it is needed; that is, if there is no session already connected to that IP address. The filter then creates a socket on this session, and makes a connection to the destination address that was provided by the client in the IFWXNetworkSocket::Connect request.

When the Firewall service detects a call to IFWXNetworkSocket::Bind, the filter searches for the related session. This session should exist because INetworkSocket::Bind always comes after IFWXNetworkSocket::Connect.

If this session does not exist, the filter sends an error packet to the client. If the session does exist, the filter creates a socket and calls IFWXNetworkSocket::Bind, IFWXNetworkSocket::Listen and IFWXNetworkSocket::Accept for the client. The filter then sends a reply to the client with the external address of the proxy server to which the external server should connect.

After accepting the connection from the server, the filter sends the client a second packet containing the internal address to which the client should send the data.

If the client sends a domain name rather than an IP address in one of these commands, a name resolution is performed by the SOCKS filter.

The sample only handles SOCKS 4/4A.

Methods Used in SOCKS 4/4a Sample Filter

The SOCKS 4/4a sample uses the following methods:

IFWXIOBuffer::GetBufferAndSize

IFWXNetworkSocket::Accept

IFWXNetworkSocket::Bind

IFWXNetworkSocket::Connect

IFWXNetworkSocket::GetPeerName

IFWXNetworkSocket::GetSockName

IFWXNetworkSocket::Listen

IFWXNetworkSocket::SetPacketFilterOptions

IFWXSession::CreateNetworkSocket

IFWXSocket::Close

IFWXSocket::Recv

IFWXSocket::Send

IFWXFilter::AttachToSession

IFWXFilter::FilterInit

IFWXFilter::FilterShutdown

IFWXFilterAdmin::InstallFilter

IFWXFilterAdmin::UninstallFilter

IFWXProxy::CreateBuffer

IFWXProxy::CreateNetworkSocket

IFWXProxy::CreatePrivateSession

IFWXProxy::DuplicateFilterHookEvents

IFWXProxy::EndHeavyBlockingOperation

IFWXProxy::IsInternal

IFWXProxy::StartHeavyBlockingOperation


SOCKS 5 Sample Filter

This sample application filter demonstrates the use of the SOCKS 5 protocol.The filter hooks into the SOCKS control channel (TCP port 1080). For each connection made to this port, an object (CSocksConnection) is created. This object identifies calls to IFWXNetworkSocket::Connect and IFWXNetworkSocket::Bind and handles them.

First, there is a negotiation between the client and the SOCKS filter, which is acting as a SOCKS server. In the negotiation the client offers the server ways to authenticate the client. The server picks one way (in this sample, user name and password) and then the client sends the server a user name and password. The server checks the authentication and if this user is allowed to make a connection, the SOCKS protocol continues as in the SOCKS 4/4a protocol.

When the CSocksConnection object detects a call to IFWXNetworkSocket::Connect, the filter creates a session for the client's IP address if it is needed; that is, if there is no session already connected to that IP address. The filter then creates a socket on this session, and makes a connection to the destination address that was provided by the client in the IFWXNetworkSocket::Connect request.

When the Firewall service detects a call to IFWXNetworkSocket::Bind, the filter searches for the related session. This session should exist because IFWXNetworkSocket::Bind always comes after IFWXNetworkSocket::Connect.

If this session does not exist, the filter sends an error packet to the client. If the session does exist, the filter creates a socket and calls INetworkSocket::Bind, IFWXNetworkSocket::Listen and IFWXNetworkSocket::Accept for the client. The filter then sends a reply to the client with the external address of the proxy server to which the external server should connect.

After accepting the connection from the server, the filter sends the client a second packet with the internal address to which the client should send the data.

If, in one of these commands, the client sends a domain name instead of an IP address, a name resolution is performed by the SOCKS filter.

The sample only handles SOCKS 5.

Methods Used in SOCKS 5 Sample Filter

The SOCKS 5 sample uses the following methods:

IFWXImpersonator::Impersonate

IFWXImpersonator::RevertToSelf

IFWXIOBuffer::GetBufferAndSize

IFWXNetworkSocket::Accept

IFWXNetworkSocket::Bind

IFWXNetworkSocket::Connect

IFWXNetworkSocket::GetPeerName

IFWXNetworkSocket::GetSockName

IFWXNetworkSocket::Listen

IFWXNetworkSocket::SetPacketFilterOptions

IFWXSession::CreateNetworkSocket

IFWXSocket::Close

IFWXSocket::Recv

IFWXSocket::Send

IFWXFilter::AttachToSession

IFWXFilter::FilterInit

IFWXFilter::FilterShutdown

IFWXFilterAdmin::InstallFilter

IFWXFilterAdmin::UninstallFilter

IFWXProxy::CreateBuffer

IFWXProxy::CreateNetworkSocket

IFWXProxy::CreatePrivateSession

IFWXProxy::DuplicateFilterHookEvents

IFWXProxy::EndHeavyBlockingOperation

IFWXProxy::IsInternal

IFWXProxy::StartHeavyBlockingOperation


Developing Web (ISAPI) Filters for ISA

Web (ISAPI) filters detect and process HTTP events. Internet Security and Acceleration (ISA) Server 2000 supports ISAPI filter development and implementation, previously available only with Internet Information Services (IIS). ISA Server operates independently of IIS, while using the definition of ISAPI functions and structures provided in the Windows 2000 Software Developer's Kit (SDK). This topic provides information about ISAPI filters, as implemented in ISA.

In the ISA Server administration tool and in the product documentation, ISAPI filters are referred to as Web filters.

For other general information regarding ISAPI filter development, see MSDN.

Note to Developers of Web filters for Internet Information Services

There are several differences between implementation of ISAPI in IIS and in ISA. These are described in ISAPI: Comparing IIS and ISA.

This section contains the following topics:

  • Introduction to Web Filters
  • Web Filter Development Tools
  • Web Filter Administration
  • Registration
  • Web Filter Samples
  • Pass-Through Authentication
  • ISAPI: Comparing IIS and ISA


Introduction to Web Filters

Web (ISAPI) filters allow you to intervene in the processing of HTTP requests. Web filters are dynamic-link libraries (DLLs) that are loaded when the ISA w3proxy service is started and stay in memory until the service shuts down. Web filters can be configured to receive special filter-event notifications that occur with each HTTP request that the ISA w3proxy service receives and with each response returned through w3proxy by an external Web server.

The figure below provides a schematic overview of the HTTP request-and-response process. A Web filter can register for and react to the events represented in the figure.

This section contains the following topics:

  • Uses of Web Filters
  • Web Filter Basics
  • ISA W3proxy Architecture


Uses of Web Filters

You can use Web (ISAPI) filters to facilitate applications that perform a number of different tasks, including:

  • Custom authentication schemes
  • Compression
  • Encryption
  • Logging
  • Traffic analysis or other request analyses
  • Request scanning and modification
  • Response scanning and modification

The ability to examine, and if necessary modify, both incoming and outgoing streams of data makes Web filters very powerful and flexible.


Web Filter Basics

When a Web (ISAPI) filter is loaded, the filter passes a structure to the ISA w3proxy service, which contains, in addition to other information, a bit field that specifies the types of filter events of which the filter should be notified. Each time one of those events occurs, an event notification is sent, and every Web filter that has specified interest in that event is notified.

Designing a Web filter requires you to consider what events your want the filter to react to, and decide what processing the filter will perform when the vent occurs. In addition to those basic design considerations, you have to select a priority for the filter, and ensure that it will be properly registered so that it is loaded by the w3proxy service.


ISA W3proxy Architecture

The ISA Web proxy service is implemented as a separate service called w3proxy. Functions provided by this service include:

  • Configurable network connections for forward and reverse proxy.
  • Parsing of HTTP 1.1 protocol headers.
  • HTTP 1.1 proxy authentication of client requests.
  • Web filter-notification support.

Note to Developers of Web Filters for Internet Information Services

There are several differences between the implementation of ISAPI in Internet Information Services (IIS) and in ISA. These are described in ISAPI: Comparing IIS and ISA.


Web Filter Development Tools

The ISA Server SDK provides the tools you need to develop Web (ISAPI) filters. These are described briefly here and in more detail in the ISAPI reference section. This section includes the following topics:

  • Web Filter Functions
  • W3proxy Notification Structures
  • ISAPI Notification Events


Web Filter Functions

Web (ISAPI) filters for the ISA Web proxy service implement the following standard entry functions:

  • GetFilterVersion
  • HttpFilterProc
  • TerminateFilter

These are described here briefly and in greater detail in the ISAPI reference.

GetFilterVersion

The GetFilterVersion function is the first entry-point function called by ISA w3proxy on your Web filter, and must be present for the filter to work. W3proxy passes a pointer to a HTTP_FILTER_VERSION data structure, which can be used to supply key filter configuration information to w3proxy. The most important information passed to w3proxy is the bitmask that contains flags that specify which notification events your filter can process, and a flag that indicates the overall processing priority for your filter.

HttpFilterProc

Whenever a notification event for which the filter has registered (in GetFilterVersion) occurs, the ISA w3proxy service calls the HttpFilterProc function. W3proxy uses this function to pass information and control to the Web filter.

TerminateFilter

This function indicates to the filter that it is going to be removed from memory. When this function is called, you should make sure that the filter closes any attachments it has made to system resources.

Note TerminateFilter is an optional function. However, you must provide this function if your filter needs to free any allocated or locked resources before being unloaded.


W3proxy Notification Structures

ISA Server's w3proxy service works with the notifications described here. Detailed information about the notification structures can be found in the ISAPI reference.

HTTP_FILTER_ACCESS_DENIED

This structure contains information about the SF_NOTIFY_ACCESS_DENIED event. The w3proxy service provides a pointer to this structure when the user is presented with an Access Denied error message.

HTTP_FILTER_AUTHENT

This structure contains information about the SF_NOTIFY_AUTHENTICATION event. The w3proxy service provides a pointer to this structure when it is authenticating a user.

HTTP_FILTER_CONTEXT

This structure is used by HTTP_FILTER_PROC to obtain information about the current request. The structure includes pointers to the following functions:

  • GetServerVariable
  • AddResponseHeaders
  • WriteClient
  • AllocMem
  • ServerSupportFunction

HTTP_FILTER_LOG

This structure contains information about the SF_NOTIFY_LOG event. The w3proxy service provides a pointer to this structure when it is writing information to a log file.

HTTP_FILTER_PREPROC_HEADERS

This structure contains information about the SF_NOTIFY_PREPROC_HEADERS event. The w3proxy service provides a pointer to this structure when it is preprocessing a request's headers.

HTTP_FILTER_RAW_DATA

This structure contains information about the SF_NOTIFY_READ_RAW_DATA or SF_NOTIFY_SEND_RAW_DATA event. The w3proxy service provides a pointer to this structure when it is reading or sending raw data.

HTTP_FILTER_SEND_RESPONSE

Web filters receive this notification immediately before they send headers to the client. The filter can inspect, modify, or add headers the client will receive as part of the response to the client's original request.

HTTP_FILTER_URL_MAP

This structure does not apply to ISA Server's implementation of ISAPI.

HTTP_FILTER_VERSION

This structure is used by the GetFilterVersion function to obtain the filter's version information.


W3proxy Notification Events

There are three types of notification events that your Web (ISAPI) filter can consider:

  • General notifications related to the request.
  • Filter priority notifications.
  • Port security setting notifications.

The notification events are described in the ISAPI reference.


Web Filter Administration

In the ISA Web proxy service, setup information is stored in ADSI or the Registry. The COM object FPCWebFilter is provided so that you can access Web filter administration information. The FPCWebFilter object is a member of the FPCWebFilters collection.

The filter information is installed and administered on an array base, so that a Web filter is installed across an array, and not on a single server of the array.

An example of Web filter administration using the ISA FPC interfaces is provided in Web Filter Setup.

Use the corresponding COM objects, as shown in Web Filter Setup.


Web Filter Setup

To set up a filter, use the FPCWebFilter and FPCWebFilters COM objects. Each FPCWebFilter object is defined by the globally unique identifier (GUID) used to add it to the FPCWebFilters collection.

Installed Web (ISAPI) filters will be enabled after the ISA Web proxy service has been stopped and restarted.

Provided here are examples showing how to add a filter, change its priority, enable it, disable it, and delete it. Each example includes code for Microsoft® Visual Basic®, and Visual Basic Scripting Edition (VBScript):

  • Adding a New Filter
  • Changing Filter Order
  • Disabling a Filter
  • Enabling a Filter
  • Deleting a Filter

Note You can also write code into a Web filter so that it can be registered and unregistered from the command line, and added to the ISA administration tool. This is described in Self-Registering Web Filters.


Adding a New Filter

Visual Basic Example

To add the filter called MyFilter, first add Microsoft Firewall Proxy and Cache Administration Library to your Project References , then use the following code:

Dim objFPC As FPC
    Dim objWebFilter As FPCWebFilter
    Dim objWebFilters As FPCWebFilters
    Set objFPC = CreateObject("FPC.Root")
    Dim MyGuid As String
    MyGuid = "{2474E364-FAF1-403f-9AFE-C2A73D667447}"
    Dim RelativePath As String
    RelativePath = "Test\MyFilter\Bin\MyFilter.dll"
    Dim Name As String
    Name = "MyFilter"
    'Add a new Web filter
    Set objWebFilter = objFPC.Arrays.GetContainingArray.Extensions.WebFilters.Add(MyGuid, Name, RelativePath, fpcFilterPriority_High, FpcFilterDirectionBoth)
    objWebFilter.Description = "Filter Description"
    objWebFilter.Name = "Filter Name"
    objWebFilter.Vendor = "Vendor Name"
    objWebFilter.Version = "1.0"
    objFPC.Save

Visual Basic Scripting Edition Example

To add the filter called MyFilter with a dynamic-link library (DLL) at relative path Test\MyFIlter\Bin\MyFilter.dll, open a file and name it FilterAdd.vbs Then insert in FilterAdd.vbs the following code (where the GUID is any arbitrary GUID that is not yet associated with any other filter):

set FPC = WScript.CreateObject("FPC.Root")
        Set filters = FPC.Arrays.GetContainingArray.Extensions.WebFilters
               Set mfilter = filters.Add("{5b6f6af3-3928-44a3-90f6-c96295c51da6}",
                                         "MyFilter", " Test\MyFilter\Bin\MyFilter.dll ", 2, 2)
        '2 == fpcFilterPriority_High
        mfilter.Description = "Filter Description"
        mfilter.Vendor = "Filter vendor"
        mfilter.Version = "1.0"
        mfilter.Enabled = True
        filters.Save
        WScript.Echo "done"


Changing Filter Order

Visual Basic Example

Use the following Visual Basic code to move the first filter one place lower in the filter order:

Set objWebFilters = objFPC.Arrays.GetContainingArray.Extensions.WebFilters
    objWebFilters.Refresh
    objWebFilters.MoveDown 1
    objWebFilters.Save

Visual Basic Scripting Edition Example

In this example, the first filter will become the second to be called among filters with the same priority. Create a file called MoveDown.vbs and insert:

set FPC = WScript.CreateObject("FPC.Root")
Set filters = FPC.Arrays.GetContainingArray.Extensions.WebFilters
filters.MoveDown  1
filters.Save
WScript.Echo "done"


Disabling a Filter

Visual Basic Example

Use the following Visual Basic code to disable an ISA Web filter:

Set objWebFilter = objFPC.Arrays.GetContainingArray.Extensions.WebFilters.Item(Guid)
    objWebFilter.Enabled = False
    objWebFilter.Save

Visual Basic Scripting Edition Example

To disable a filter with a known GUID, create a file called Disable.vbs and insert:

set FPC = WScript.CreateObject("FPC.Root")
Set filters = FPC.Arrays.GetContainingArray.Extensions.WebFilters
Set mfilter = filters("{5b6f6af3-3928-44a3-90f6-c96295c51da6}")
mfilter.Enabled = False
mfilter.Save
WScript.Echo "done"


Enabling a Filter

Visual Basic Example

Use the following Visual Basic code to enable an ISA Web filter:

Set objWebFilter = objFPC.Arrays.GetContainingArray.Extensions.WebFilters.Item(Guid)
objWebFilter.Enabled = True
objWebFilter.Save

Visual Basic Scripting Edition Example

To enable the filter, create a file called Enable.vbs and insert:

set FPC = WScript.CreateObject("FPC.Root")
Set filters = FPC.Arrays.GetContainingArray.Extensions.WebFilters
Set mfilter = filters("{5b6f6af3-3928-44a3-90f6-c96295c51da6}")
mfilter.Enabled = True
mfilter.Save
WScript.Echo "done"


Deleting a Filter

Visual Basic Example

Use the following Visual Basic code to remove an ISA Web filter.

Set objISAPIFilters = objFPC.Arrays.GetContainingArray.Extensions.WebFilters
objWebFilters.Remove (Guid)
objWebFilters.Save

Visual Basic Scripting Edition Example

To delete the filter, create a file called Delete.vbs and insert:

set FPC = WScript.CreateObject("FPC.Root")
Set filters = FPC.Arrays.GetContainingArray.Extensions.WebFilters
filters.Remove("{5b6f6af3-3928-44a3-90f6-c96295c51da6}")
filters.Save
WScript.Echo "done"


Registration

Web filters that will be used by the ISA Web proxy service have to be registered under ISA/Arrays/ISAPI-Filters. The administrator will then have access to filter activation through the administration graphic interface.

There are two steps in the filter registration process:

  1. Setup, including copying the filter DLL to an appropriate location, and adding the filter to ISA storage. This process is shown in Web Filter Setup.
  2. Subscription, using the GetFilterVersion function. This action assigns the notification for which the filter will be called. Subscription occurs each time the ISA Web proxy service is restarted.


Self-Registering Web Filters

You can create a Web (ISAPI) filter that contains code enabling self-registration of the filter. The code is demonstrated in the Web filter sample provided with this documentation. The sample extends the ISA administration tool by adding a Web (ISAPI) filter and displaying the filter's information in the tool's results pane. The sample files are in the Isapifilters directory, under the samples directory in the SDK.

This section contains the following topics:

  • Building the ISA Web Filter Sample
  • ISA Web Filter Sample Administration Steps


Building the ISA Web Filter Sample

The sample is included in the samples folder of the SDK, in the subfolder Isapifilters. To build the sample take the following steps:

To build the ISA Web filter included in the SDK

  1. Open Microsoft Visual Studio®.
  2. Open the sample workspace, isapiresponsemodifier.dsw.
  3. To see the project files, select the View menu, and then workspace.
  4. Press the F7 key to build the sample.

These steps create Isapiresponsemodifier.dll.


ISA Web Filter Sample Administration Steps

ISA and IIS let you accumulate server request chunks into a complete request. The Isapiresponsemodifier sample filter is an example that collects the response chunks and then allows you to change them depending on the complete request.

This section contains the following topics:

  • Register the Web Filter From the Command Line
  • Unregister the Web Filter From the Command Line
  • Add the Web Filter to ISA


Register the Web Filter From the Command Line

To install the filter, type this line at the command prompt:

regsvr32 Isapiresponsemodifier.dll

This command is carried out by the code in the function DllRegisterServer in the Isapiresponsemodifier sample. The filter developer writes this function. The code from the Isapiresponsemodifier filter sample is shown below.

// DllRegisterServer - Adds entries to the system registry
STDAPI DllRegisterServer(void)
{
    HRESULT hr = RegisterIsapiFilter(true);
    return FAILED(hr) ? S_FALSE : S_OK;
}


Unregister the Web Filter From the Command Line

To uninstall the filter, type this line at the command prompt:

regsvr32 -u Isapiresponsemodifier.dll

This command is also carried out by a function that the filter developer writes. The code from the Isapiresponsemodifier sample is shown here.

// DllUnregisterServer - Removes entries from the system registry

STDAPI DllUnregisterServer(void)
{
    HRESULT hr = RegisterIsapiFilter(false);
    return hr;
}


Add the Web Filter to ISA

To implement the sample filter and display the filter in the results pane of the ISA administration tool, use the RegisterIsapiFilter function to register the filter with ISA. This function is also called by the DllRegisterServer and DllUnregisterServer functions.

The following is the code of the RegisterIsapiFilter function. This code is taken from the file ISapiFltrRegister.cpp, included in the Isapiresponsemodifier directory:

static HRESULT RegisterIsapiFilter(bool fRegister)
{
    HRESULT hr;
    ISALIB::IFPC *pIISA  = NULL;

    // Get instance of filter admin object.
    hr = CoInitialize(NULL);

    if (FAILED(hr)) return hr;

    hr = CoCreateInstance(
        CLSID_FPC,
        NULL,
        CLSCTX_SERVER,
        IID_IFPC,
        (void**)&pIISA);

    if (FAILED(hr)) return hr;

    ISALIB::IFPCArrays *pIISAArrs = pIISA->Arrays;
    ISALIB::IFPCArray  *pIISAArr =  pIISAArrs->GetContainingArray();
    ISALIB::IFPCExtensions *pIExtensions =  pIISAArr->Extensions;
    ISALIB::IFPCWebFilters *pIsapifilters = pIExtensions->WebFilters;
    ISALIB::IFPCWebFilter *pFilter = NULL;
    if (fRegister)
    {
        _bstr_t bstr(StrGuid);

        try
        {
            pFilter =  pIsapifilters->Add(bstr,"ISAPI Filter",FilterRelativePath,ISALIB::fpcFilterPriority_Medium,ISALIB::fpcFilterDirectionBoth);
            pFilter->PutDescription("Filter Description");
            pFilter->PutVendor("Microsoft");
            pFilter->PutVersion("1.0");
        //  pFilter->PutEnabled(TRUE);
        }
        catch(_com_error& err)
        {
            if(err.Error() != HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS))
            {
                hr = E_FAIL;
            }
        }

        if (pFilter)
        {
            pFilter->Save();
        }
    }
    else
    {
        try
        {

            pIsapifilters->Remove(StrGuid);
        }
        catch(_com_error& err)
        {
            if(err.Error() != HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND))
            {
                hr = E_FAIL;
            }
        }

    }

    pIsapifilters->Save();
    pIsapifilters->Refresh();

    if(pIISA)
        pIISA->Release();

    CoUninitialize( );

    return hr;
}


Web Filter Samples

Sample Web (ISAPI) filters developed using the ISA SDK are provided in the Samples\Isapifilters directory on the ISA CD-ROM in the SDK directory. The following samples are provided:

  • Isapiresponsemodifier


Isapiresponsemodifier

ISA Server's implementation of ISAPI allows you to accumulate request chunks, to form a complete request, by means of a Web filter.

The Isapiresponsemodifier filter collects the response chunks and then allows you to change them depending on the complete response. This filter is an adaptation of the filter that IIS uses for compression. (Original filter written by David Treadwell on July 1997.)

The filter works with two notifications. In SF_NOTIFY_Send_Raw_Data , it collects the response's chunks, but sends 0 bytes instead of the chunks. Then, when all the chunks of this response have passed SF_NOTIFY_Send_Raw_Data notifications, ISA Server thinks the complete response was sent. It therefore calls the SF_NOTIFY_End_Of_Request notification. The filter sends the complete response in the SF_NOTIFY_End_Of_Request notification.


Pass-Through Authentication

With pass-through authentication, a client can send credentials directly to an upstream server, without sending credentials to the local ISA Server.

In a simple scenario, the downstream ISA Server does not request credentials at all, while the upstream server requires authentication from the client. The process works as follows:

  • The client requests an object from the ISA Server.
  • The ISA Server routes the request to an upstream server, which requests credentials from the client.
  • The client returns the credentials, by way of the ISA Server, directly to the upstream server. The downstream ISA Server does not access the client credentials.

Note that in this case, Web filters running on the ISA Server will not access the credentials passed by the client to the upstream server.

In another scenario, both the ISA Server and the upstream server require credentials. In this case, the process works as follows:

  • The client connects to the ISA Server.
  • The ISA Server requests credentials, as dictated by publishing or access policy rules.
  • The client returns credentials to the ISA Server.
  • The ISA Server passes the request to the upstream server.
  • The upstream server requests client credentials.
  • The client returns credentials to the ISA Server.
  • The ISA Server recognizes the client as already authenticated, and passes the credentials to the upstream server.


ISAPI: Comparing IIS and ISA

The ISA Web proxy service supports the Web (ISAPI) filter extensibility model, allowing third-party developers to examine and change the HTTP request-and-response flow using Web filters. ISAPI extensions are not supported.

The ISA Web proxy service manages communication with clients, and therefore does not rely on IIS. The ISA Web proxy service provides the functions necessary for the implementation of Web filters. Web filters developed for IIS will work with the ISA Web proxy service because the APIs are unchanged.

There are several important differences between ISAPI support in IIS and in ISA.

Architecture

Web (ISAPI) filters for IIS are typically installed on a Web server. Web filters for ISA are installed on an ISA server, between the Web server and the Web client, and therefore act as conduits for requests to all external and internal sites. There is thus no local site or content, and no direct access to Web server files.

Functions

The support for general ISAPI functions, server support functions, and notification-specific functions in ISA differs slightly from IIS. The following table compares support for ISAPI functions in IIS and in ISA Server.

Function | Task | ISA Server Support | IIS Support
GetServerVariable |  | Yes. Not all variables are supported | Yes.
AddResponseHeaders |  | Yes. | Yes.
WriteClient |  | Yes. | Yes.
AllocMem |  | Yes. | Yes.
ServerSupportFunction | SF_REQ_ADD_HEADERS_ON_DENIAL | Yes. | Yes.
 | SF_REQ_DISABLE_NOTIFICATIONS | Yes. | Yes.
 | SF_REQ_GET_CONNID | Returns 0 | Supported by versions until IIS 4.0; otherwise, returns 0
 | SF_REQ_GET_PROPERTY only for SF_PROPERTY_INSTANCE_NUM_ID | Returns 0 | Yes.
 | SF_REQ_NORMALIZE_URL | Yes. | Yes.
 | SF_REQ_SEND_RESPONSE_HEADER | Yes. | Yes.
 | SF_REQ_SET_NEXT_READ_SIZE | Yes. | Yes.
 | SF_REQ_SET_PROXY_INFO | No. | Yes.
SF_NOTIFY_SEND_RESPONSE |  | Not used when w3proxy sends a response. Used when a filter generates a response using the SF_REQ_SEND_RESPONSE_HEADERS server support function. | Yes.
SF_STATUS_REQ_FINISHED_KEEP_CONN |  | Treated the same as SF_STATUS_REQ_FINISHED. After this notification is received, the connection is closed. | Treated the same as SF_STATUS_REQ_FINISHED, except that the server should keep the TCP session open if the option was negotiated.

Administration

Administration, setup and registration are significantly different in ISA. For specific information and procedures see Web Filter Setup and Registration.

IIS stores configuration information in the Microsoft Active Directory™, whereas the ISA Web proxy service uses the ISA administration COM objects to store and retrieve filter configuration information.

Note Web filters developed for Microsoft Proxy Server 2.0 are not binary-compatible with ISA because of new notifications, setup requirements, and storage functionality.


Managing the ISA Server Cache

The ISA administration COM objects allow you to administer the cache programmatically, automate administrative tasks related to the cache, and extend cache performance by using the FetchURL method.

This section contains the following topics:

  • Introduction to the ISA Server Cache Objects
  • Extending the Cache


Introduction to the ISA Server Cache Objects

The ISA Server cache is administered through the cache COM objects. The objects are described briefly here, and in more detail in the ISA Server reference section.

See the ISA administration object model to view how the cache-related objects fit into the entire object hierarchy.

FPCCache Object

The FPCCache object is primarily a container for most of the configuration objects listed below. You can access the FPCCacheConfiguration and FPCCacheContents objects directly through this object. You can access the FPCActiveCacheConfiguration, FPCFTPCacheConfiguration, and FPCHTTPCacheConfiguration objects through the FPCCacheConfiguration object.

This object is a property of the FPCArray object, and administers the cache for the entire array.

FPCCacheConfiguration Object

The FPCCacheConfiguration object is primarily a container for the FPCActiveCacheConfiguration, FPCHTTPCacheConfiguration, and FPCFTPCacheConfiguration objects, which provide access to, respectively, the active caching, HTTP caching, and FTP caching configuration settings.

FPCActiveCacheConfiguration Object

The FPCActiveCacheConfiguration object provides access to the active cache configuration settings of an ISA Server computer.

Active caching is the opposite of passive caching, which is caching in reaction to a specific user request for content. If there is room in the cache, the requested object will be stored in the cache.

Through active caching, ISA can automatically determine the most popular Web sites visited by its clients, determine how frequently those sites update their content, and then automatically obtain and cache the new content when the old content in the cache has expired. Once it is activated, active caching works automatically.

FTPCacheConfiguration Object

The FTPCacheConfiguration object provides access to the FTP cache configuration settings of an ISA Server computer. FTP caching is the caching of FTP objects. You can use this object to choose whether to activate FTP object caching and configure FTP caching settings.

HTTPCacheConfiguration Object

The HTTPCacheConfiguration object provides access to the HTTP cache configuration settings of an ISA Server computer. HTTP caching is the caching of HTTP objects. You can use this object to choose whether to activate HTTP object caching and configure HTTP caching settings.

FPCCacheContents Object

The FPCCacheContents object permits greater control over active caching through the FPCCacheContents.FetchUrl method. This method is used to specify to the cache the URLs to be prefetched or actively retrieved from the Internet and stored in the cache.

FPCScheduledContentDownload Collection

The FPCScheduledContentDownload collection allows you to create a list of predefined scheduled content download tasks. Each task is represented by an FPCScheduledContentDownloadConfig object.

FPCCacheDrive Object and FPCCacheDrives Collection

The FPCCacheDrive object represents a single cache-drive object of an ISA Server computer, and the FPCCacheDrives collection represents a collection of cache drives. The FPCCacheDrive objects allow an administrator to programmatically access and adjust size of the drives.


Extending the Cache

This section describes how to extend the cache using the FetchUrl method. It also describes how to delete a cached object using FetchUrl. FetchUrl is accessible both as an administration COM object method and as an interface method.

This section contains the following topics:

  • Using FetchUrl to Extend the Cache
  • Using FetchUrl to Delete a Cached Object


Using FetchUrl to Extend the Cache

The Web proxy service normally fetches objects from the Internet and caches them automatically as proxy clients request them (passive caching). In addition, the Web proxy service will automatically keep certain popular objects "fresh" within its cache by fetching them itself (active caching). However, occasions occur when an application needs a mechanism to override these automatic operations and exercise greater control over the source of objects that are placed in the cache, or the length of time that they are to remain cached. For example, an application may need to:

  • Make data downloaded from a nonstandard network source (such as a satellite or private network) accessible to Web browsers as if it was normal Internet data.
  • Update certain objects within the Web proxy's cache on a fixed schedule.
  • Place objects in the Web proxy's cache that would normally not be cached.

This function facilitates these operations by allowing an application to cause the Web proxy service to fetch an object from a given location (FetchUrl) and store the object in its cache. The object may also be assigned a new name (CacheUrl), which Web proxy clients will use to retrieve the object from Web proxy cache and/or assigned a particular Time to Live (TTL) within the cache.

FetchURL Usage Examples

Here are two examples of how you might use the FetchURL method.

Example 1

For example consider a proxy installation with a very slow Internet connection that requires quick access to the fictional Web site called "fiction.microsoft.com". One solution to this problem would be for the owners of fiction.microsoft.com to produce a CD-ROM that contained all the content found on their Web site and mail it weekly to the proxy customer. An application could use this function to cause the proxy to fetch the data from the CD-ROM and store it in the cache as if it was data from the Internet fiction.microsoft.com site, with a TTL of one week. A complication is that the proxy only supports the HTTP, FTP, and gopher protocols, so the data cannot be fetched directly from the CD-ROM. There are several possible solutions to this problem; for example:

  • The data on the CD-ROM could be copied into the publishing directory of an HTTP or FTP server or a publishing server could be configured to directly serve the data from the CD-ROM. This is a good solution if the data is provided as normal files (HTML, GIF, and so forth) without any HTTP headers already added from the original publishing server, fiction.microsoft.com. If the files already contained HTTP headers from fiction.microsoft.com, serving the data from another HTTP server would add a second set of headers which would render the objects unintelligible to the proxy or to browsers.
  • If the files already contain a set of HTTP headers (for example, if they were the product of a raw Internet download of the contents of fiction.microsoft.com instead of a copy of the data files from the fiction.microsoft.com Web servers), the easiest solution might be to write an alternative HTTP server application that would serve up the data files without adding HTTP headers. The HTTP server application would call FetchUrl in order to listen on the external socket and receive the data before it gets to the w3proxy service. This would allow the application to have complete control over the data being sent to w3proxy. This method is also particularly useful when the application needs to perform simple housekeeping operations on cached objects such as generating a "304 Not Modified" HTTP response to leave an object unmodified but extend its TTL, or a "404 Gone" response to delete an object from the cache.

Example 2

In a Web hosting scenario, your organization may regularly update part of the information on its Web site. All or part of the Web site data can be cached on an ISA Server cache. When the Web site information changes, the cache will have to be updated. You can use the FetchUrl method to streamline the update process. In the central database for the Web site information, create an application that generates a file listing all of the files that have changed. Use FetchUrl to retrieve that file. Parse the file to create a list of files that require updating. Then use FetchUrl to retrieve each updated file from the database. This use of FetchUrl allows you to update only the cache files that have changed.

Remarks

To retrieve an HTTP object in response to a call to FetchUrl, the Web proxy service uses the normal HTTP GET method to the URL specified by FetchUrl. If there is already a cached copy of the URL specified by CacheUrl (either loaded into the proxy previously by normal operations or by an earlier call to FetchUrl) the proxy will include an "If-Modified-Since" HTTP header in the request, also known as a conditional GET. The response to a conditional GET may be either a new copy of the data that will be stored into the cache or an HTTP status code 304 "Not Modified" response which will cause the proxy to extend the TTL of the object without changing the contents of the data in the cache.

If FetchUrl is used on an array containing more than one proxy server, the object will automatically be fetched by the single array member that is the designated owner of that object according to the CARP algorithm.

Example Code

The following code sample demonstrates VBScript usage of FetchUrl.

' When using VBScript, the enum values should be declared as constants
' or explicit numeric values must be used instead

Const fpcTtlIfNone = 1
Const fpcFetchSynchronous = 4

customTTL = 10     '

Set root = CreateObject("FPC.Root")
Set myCache = root.Arrays.CurrentArray.Cache.CacheContents

' we wish to fetch "http://foo.com/bar.htm" and to store it in the cache under the name "http://cache_server/bar.htm"

myCache.FetchURL "http://foo.com/bar.htm", "http://cache_server/bar.htm",  customTTL,  fpcTtlIfNone +  fpcFetchSynchronous


Using FetchUrl to Delete a Cached Object

You can use the FetchUrl method to delete a cached HTTP object. Deleting objects by means of FetchUrl will work for any cached object, whether or not it was cached using FetchUrl.

To delete an HTTP object from the cache, set lpszFetchUrl = <empty string>, lpszCacheUrl = <cachedURL>, TtlInMinutes = 0 and Flags = 0.

Note With flags = 0, the default flag setting, the operation is performed as a non-blocking operation. If flags = FETCH_SYNCHRONOUS, this will be a blocking operation.


Internet Security and Acceleration Reference

This section contains reference materials related to the Microsoft Internet Security and Acceleration (ISA) Server 2000 Software Developer's Kit (SDK). It includes information about ISA administration COM objects, programming interfaces for application filter development, and related structures and enumerated types. This section also provides a glossary of terms and a table of objects and their corresponding globally unique identifiers (GUIDs).

The ISA reference section contains the following topics:

  • Administration Reference
  • Firewall Reference
  • Cache Reference
  • ISAPI Reference
  • Error Codes
  • Globally Unique Identifiers
  • Glossary


Administration Reference

This section defines the Internet Security and Acceleration (ISA) Server 2000 administration objects and includes descriptions of objects, their properties and methods.

This section contains the following topics:

  • Objects
  • Enumerated Types
  • Administration Object Error Codes


Objects

The ISA administration COM object sections display Microsoft® Visual Basic® syntax; however, you can write programs using these objects in any language that supports COM. See the ISA Administration Object Model for a diagram of the administration COM object hierarchy. The diagram shows the beginning of the hierarchy, starting with the root object.

The administration objects expose two types of application programming interfaces (APIs) — one API allows for configuration of stored ISA settings, and the other allows for configuration of services that are currently running. For example, the session monitoring objects (FPCWebSession and FPCFirewallSession) permit programmatic monitoring of sessions currently running, while most other administration COM objects allow for programmatic configuration of various internal ISA settings. For more detailed examples of object use, see ISA Administration Scripting.

  • FPC Object
  • FPCAccessControlEntry Object
  • FPCAccessControlList Collection
  • FPCAccount Object
  • FPCAccounts Collection
  • FPCActiveCacheConfiguration Object
  • FPCAdapter Object
  • FPCAdapterList Collection
  • FPCAlert Object
  • FPCAlerts Collection
  • FPCAlertAction Object
  • FPCAlertActions Collection
  • FPCAlertInfo Object
  • FPCAlertNotification Object
  • FPCApplicationFilter Object
  • FPCApplicationFilters Collection
  • FPCArray Object
  • FPCArrays Collection
  • FPCArrayPolicyConfig Object
  • FPCArrayPolicyConfigs Collection
  • FPCAutoDial Object
  • FPCBackupRoute Object
  • FPCBandwidthPriority Object
  • FPCBandwidthPriorities Collection
  • FPCBandwidthRule Object
  • FPCBandwidthRules Collection
  • FPCCache Object
  • FPCCacheConfiguration Object
  • FPCCacheContents Object
  • FPCCacheDrive Object
  • FPCCacheDrives Collection
  • FPCClientAddressSet Object
  • FPCClientAddressSets Collection
  • FPCClientAutoScript Object
  • FPCClientBackupRoute Object
  • FPCClientConfigSettings Collection
  • FPCClientSettingsSection Object
  • FPCContentGroup Object
  • FPCContentGroups Collection
  • FPCCredentials Object
  • FPCDestination Object
  • FPCDestinationSet Collection
  • FPCDestinationSets Collection
  • FPCDialupEntry Object
  • FPCDialupEntries Collection
  • FPCDirectAddressDestination Object
  • FPCDirectAddressDestinations Collection
  • FPCDirectIpDestination Object
  • FPCDirectIpDestinations Collection
  • FPCDiskDrive Object
  • FPCDiskDrives Collection
  • FPCEnterprise Object
  • FPCEnterprisePolicy Object
  • FPCEnterprisePolicies Collection
  • FPCEventDefinition Object
  • FPCEventDefinitions Collection
  • FPCExtensions Object
  • FPCFilterProtocol Object
  • FPCFilterProtocols Collection
  • FPCFirewallClientConfig Object
  • FPCFirewallChaining Object
  • FPCFTPCacheConfiguration Object
  • FPCHTTPCacheConfiguration Object
  • FPCIpPacketFilter Object
  • FPCIpPacketFilters Collection
  • FPCIpRange Object
  • FPCLAT Collection
  • FPCLATEntry Object
  • FPCLDT Collection
  • FPCLDTEntry Object
  • FPCListenEntry Object
  • FPCListenEntries Collection
  • FPCLog Object
  • FPCLogs Collection
  • FPCNetworkConfiguration Object
  • FPCPNATServerMapping Object
  • FPCPNATServerMappings Collection
  • FPCPolicyElements Object
  • FPCPrimaryRoute Object
  • FPCProtocolConnection Object
  • FPCProtocolConnections Collection
  • FPCProtocolDefinition Object
  • FPCProtocolDefinitions Collection
  • FPCProtocolRule Object
  • FPCProtocolRules Collection
  • FPCProxyClientConfig Object
  • FPCProxyTunnelPortRange Object
  • FPCProxyTunnelPortRanges Collection
  • FPCPublishing Object
  • FPCRasPhoneBookEntries Collection
  • FPCRef Object
  • FPCRefs Collection
  • FPCRoutingRule Object
  • FPCRoutingRules Collection
  • FPCSchedule Object
  • FPCScheduledContentDownload Collection
  • FPCScheduledContentDownloadConfig Object
  • FPCSchedules Collection
  • FPCSecurityDescriptor Object
  • FPCServer Object
  • FPCServers Collection
  • FPCSignaledAlert Object
  • FPCSignaledAlerts Collection
  • FPCSiteAndContentRule Object
  • FPCSiteAndContentRules Collection
  • FPCSnapinNode Object
  • FPCSSLCertificate Object
  • FPCSSLCertificates Collection
  • FPCVendorParametersSet Object
  • FPCVendorParametersSets Collection
  • FPCWebBrowserClientConfig Object
  • FPCWebFilter Object
  • FPCWebFilters Collection
  • FPCWebProxy Object
  • FPCWebPublishingRule Object
  • FPCWebPublishingRules Collection
  • FPCWebRequestConfiguration Object
  • FPCWebSession Object
  • FPCWebSessionAdditionalInfo Object
  • FPCWebSessions Collection
  • FPCFirewallSession Object
  • FPCFirewallSessionConnection Object
  • FPCFirewallSessionConnections Collection
  • FPCFirewallSessions Collection


FPC Object

The FPC object is the root of the administration object hierarchy, and provides programmatic access to all of the other FPC objects. See ISA Administration Object Model for a diagram of the entire hierarchy.

Creating this root object is the first step in making any programmatic changes to ISA. Using Visual Basic, you can create it with the following code:

Dim objFPC As New FPCLib.FPC

The CreateObject function is also available to Visual Basic programmers and so, alternatively, the following can be used:

  Dim objFPC
  Set objFPC = CreateObject("FPC.Root")

After the FPC object is created, objects below it in the hierarchy can be accessed through the root object's properties. The Arrays property returns a collection of all ISA arrays within the root node, and it is through this property that you can access and change configuration settings of server arrays.

See ISA Administration Scripting for multiple examples of use of the FPC root object.

Note to C++ Programmers

This object implements the IFPC interface.

Methods

The following table lists the methods of the FPC root object.

Method | Description
Refresh | Reads all the items from persistent storage.
Save | Saves current configuration to the persistent storage.

Properties

The following table lists the properties of the FPC root object.

Property | Description
Arrays | Returns a collection of all ISA arrays.
EnterprisePolicies | Returns an object that defines global policy behavior.
Type | Retrieves the array's type.
VendorParametersSets | Returns a reference to an object that stores vendor-specific data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPC.Arrays Property

Returns a collection of all FPC arrays within the FPC root node. Using this arrays property, you can access individual servers within each array.

Syntax

[ collFPCArrays = ] FPC.Arrays

Possible Values

collFPCArrays
Reference to an FPCArrays collection.

The property is read-only.

Remarks

The following code uses the Arrays property to access the FPCArray.Name property of the first array in the FPC root object:

Dim objFPC As New fpcLib.FPC
Dim arrayName As String
arrayName = objFPC.Arrays(1).Name

Applies To

FPC


FPC.EnterprisePolicies Property

Returns an object that defines the global policy behavior.

Syntax

[ oFPCEnterprise = ] FPC.EnterprisePolicies

Possible Values

oFPCEnterprise
Reference to the FPCEnterprise object.

The property is read-only.

Applies To

FPC


FPC.Refresh Method

Reads all the items from persistent storage, discarding any changes that were not saved..

Syntax

FPC.Refresh()

Applies To

FPC


FPC.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made in scripts and programs will not be saved until after the Save method is called.

Syntax

FPC.Save()

Remarks

In the following example, the new name assigned to the FPCArray object will not be saved until the Save method is called in the last line of code.

Dim objFPC As New FPCLib.FPC

Dim arrayName As String
arrayName = "myNewArray"
objFPC.Arrays(1).Name = arrayName 'no changes saved yet
objFPC.Save 'changes saved

Applies To

FPC


FPC.Type Property

Retrieves the array's type.

Syntax

[ FPCArrayType = ] FPC.Type

Possible Values

FPCArrayType
Value that specifies the type of ISA array. It can have a value of the FpcArrayType enumeration.

The property is read-only.

Applies To

FPC


FPC.VendorParametersSets Property

Returns a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection will be backed up with all other FPC objects.

Syntax

[ collFPCVendorParametersSets = ] FPC.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPC


FPCAccessControlEntry Object

The FPCAccessControlEntry object allows you to access and manipulate individual access-control entries of the parent object. An FPCAccessControlEntry object stipulates who can access an object and what type of access will be granted. It also specifies whether the access-control settings can be propagated from the object to any of its children.

An object can have a number of access-control entries, one for each client or a group of clients. Access control entries are maintained in an FPCAccessControlList collection.

The FPCAccessControlEntry object is a member of an FPCAccessContolList collection.

Note to C++ Programmers

This object implements the IFPCAccessControlEntry interface.

Properties

The following table lists the properties of the FPCAccessControlEntry object.

Property | Description
AccessMask | Sets or returns the access mask for this FPCAccessControlEntry object.
AceFlags | Sets or returns the FPCAccessControlEntry flag values.
AceType | Sets or returns the FPCAccessControlEntry object type.
Flags | Sets or returns the FPCAccessControlEntry flag values.
InheritedObjectType | Sets or returns the FPCAccessControlEntry inherited object type.
ObjectType | Sets or returns the FPCAccessControlEntry object type.
Trustee | Sets or returns the FPCAccessControlEntry trustee.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAccessControlEntry.AccessMask Property

Sets or returns the access mask for this FPCAccessControlEntry object.

Syntax

FPCAccessControlEntry.AccessMask [ = lnAccessMask ]

Possible Values

lnAccessMask
Long value that specifies the access mask for this FPCAccessControlEntry object.

The property is read-write.

Applies To

FPCAccessControlEntry


FPCAccessControlEntry.AceFlags Property

Sets or returns the FPCAccessControlEntry flag values.

Syntax

FPCAccessControlEntry.AceFlags [ = lAceType ]

Possible Values

lAceType
Long value that specifes the FPCAccessControlEntry flag values.

The property is read-write.

Applies To

FPCAccessControlEntry


FPCAccessControlEntry.AceType Property

Sets or returns the FPCAccessControlEntry object type.

Syntax

FPCAccessControlEntry.AceType [ = lAceType ]

Possible Values

lAceType
Long value that specifes the FPCAccessControlEntry object type.

The property is read-write.

Applies To

FPCAccessControlEntry


FPCAccessControlEntry.Flags Property

Sets or returns the FPCAccessControlEntry flag values.

Syntax

FPCAccessControlEntry.Flags [ = lFlags ]

Possible Values

lFlags
Long value that specifes the FPCAccessControlEntry flag values.

The property is read-write.

Applies To

FPCAccessControlEntry


FPCAccessControlEntry.InheritedObjectType Property

Sets or returns the FPCAccessControlEntry inherited object type.

Syntax

FPCAccessControlEntry.InheritedObjectType[ = sInheritedObjectType ]

Possible Values

sInheritedObjectType
String value that specifies the FPCAccessControlEntry inherited object type.

The property is read-write.

Applies To

FPCAccessControlEntry


FPCAccessControlEntry.ObjectType Property

Sets or returns the FPCAccessControlEntry object type.

Syntax

FPCAccessControlEntry.ObjectType [ = sObjectType ]

Possible Values

sObjectType
String that specifes the FPCAccessControlEntry object type.

The property is read-write.

Applies To

FPCAccessControlEntry


FPCAccessControlEntry.Trustee Property

Sets or returns the FPCAccessControlEntry trustee.

Syntax

FPCAccessControlEntry.Trustee [ = sTrustee ]

Possible Values

sTrustee
String value that specifes the FPCAccessControlEntry trustee.

The property is read-write.

Applies To

FPCAccessControlEntry


FPCAccessControlList Collection

The FPCAccessControlList collection contains a group of FPCAccessControlEntry objects that provide finely tuned access control to the same ADSI object for different clients. In general, different providers implement different access controls. The object's behavior is thus highly provider-specific.

Before you can work with FPCAccessControlEntry objects, you must obtain the FPCAccessControlList to which they belong. FPCAccessControlList collections are managed by security descriptors and can be in the form of a discretionary access-control list or a system access-control list. Using this collection, you can retrieve FPCAccessControlEntry objects, add new objects to the list, or remove existing objects.

The FPCAccessControlList object is a property of an FPCSecurityDescriptor object.

Note to C++ Programmers

This object implements the IFPCAccessControlList interface.

Methods

The following table lists the methods of the FPCAccessControlList collection.

Method | Description
AddAce | Adds an FPCAccessControlEntry object to the list.
CopyAccessList | Returns a copy of the current FPCAccessControlList collection.
RemoveAce | Removes an FPCAccessControlEntry object from the list.

Properties

The following table lists the properties of the FPCAccessControlList collection.

Property | Description
AceCount | Sets or returns the count of FPCAccessControlEntry objects in the collection.
AclRevision | Sets or returns the FPCAccessControlList collection revision number.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAccessControlList.AceCount Property

Sets or returns the count of FPCAccessControlEntry objects in the collection.

Syntax

[ lCount = ] FPCAccessControlList.AceCount

Possible Values

lCount
Long value that specifies the count of FPCAccessControlEntry objects in the collection.

The property is read-only.

Applies To

FPCAccessControlList


FPCAccessControlList.AclRevision Property

Sets or returns the FPCAccessControlList collection revision number.

Syntax

FPCAccessControlList.AclRevision [ = lAclRevision ]

Possible Values

lAclRevision
Long value that specifies the FPCAccessControlList collection revision number.

The property is read-write.

Applies To

FPCAccessControlList


FPCAccessControlList.AddAce Method

Adds an FPCAccessControlEntry object to the list.

Syntax

AccessControlList.AddAce( oFPCAccessControlEntry )

Parameters

oFPCAccessControlEntry
Reference to the FPCAccessControlEntry object being added.

Applies To

FPCAccessControlList


FPCAccessControlList.CopyAccessList Method

Returns a copy of the current FPCAccessControlList collection.

Syntax

[ collFPCAccessControlList = ] FPCAccessControlList.CopyAccessList()

Return Values

collFPCAccessControlList
Reference to an FPCAccessControlList collection.

Applies To

FPCAccessControlList


FPCAccessControlList.RemoveAce Method

Removes an FPCAccessControlEntry object from the list.

Syntax

FPCAccessControlList.RemoveAce( oFPCAccessControlEntry )

Possible Values

oFPCAccessControlEntry
Reference to the FPCAccessControlEntry object to be removed.

Applies To

FPCAccessControlList


FPCAccount Object

The FPCAccount object defines an account for a user or a group of users. You can use this object to determine the account type, modify the account's status, and read the domain and name of the account.

The FPCAccount object is a member of the FPCAccounts collection.

Note to C++ Programmers

This object implements the IFPCAccount interface.

Properties

The following table lists the properties of the FPCAccount object.

Property | Description
Account | Sets or returns the domain and name of the account.
AccountStatus | Sets or returns a value that determines whether this account serves as an "Include" entity or an "Exclude" entity in the collection.
AccountType | Returns the type of the account.
Sid | Returns the security identifier (SID).
VendorParametersSets | Returns a reference to an object for storing and loading of custom data into the FPCAccount object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAccount.Account Property

Sets or returns the domain and name of the account.

Syntax

FPCAccount.Account [ = sAccount ]

Possible Values

sAccount
String that specifies the domain and name, in domain\name format.

The property is read-write.

Applies To

FPCAccount


FPCAccount.AccountStatus Property

Sets or returns a value that determines whether this account serves as an "Include" entity or an "Exclude" entity in the collection.

Syntax

FPCAccount.AccountStatus [ = Status ]

Possible Values

Status
Specifies the status. It can have a value from the FpcIncludeStatus enumerated type.

The property is read-write.

Applies To

FPCAccount


FPCAccount.AccountType Property

Returns the account type.

Syntax

[ Type = ] FPCAccount.AccountType

Possible Values

Type
Integer value that specifies the account type. It can have a value from the FpcAccountTypes enumeration.

The property is read-only.

Applies To

FPCAccount


FPCAccount.Sid Property

This property returns the security identifier (SID). An SID is a unique name that identifies a user logged on to the Windows NT/Windows 2000 security system. An SID can identify an individual user or a group of users.

Syntax

[ Sid = ] FPCAccount.Sid

Possible Values

Sid
Integer value that retrieves the SID.

The property is read-only

Applies To

FPCAccount


FPCAccount.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCAccount object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCAccount.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to an FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCAccount


FPCAccounts Collection

The FPCAccounts collection holds a group of FPCAccount objects. You can use this collection to define a set of accounts to be associated with a site and content rule or a protocol rule. This set is defined by accounts to include and by accounts to exclude. For example, you can define a set of "all users but John" by adding the account name for the all-users group as "included" and then adding John's account as "excluded".

This collection is a property of the FPCSiteAndContentRule and FPCProtocolRule objects.

Note to C++ Programmers

This collection implements the IFPCAccounts interface.

Methods

The following table lists the methods of the FPCAccounts collection.

Method | Description
Add | Creates a new account object, inserts it into the collection, and returns a reference to it.
Item | Retrieves the given FPCAccount object from the collection.
Refresh | Reads all of the FPCAccount objects from persistent storage, discarding any changes to the objects that were not saved.
Remove | Removes an account from the collection.
RemoveAll | Clears the collection of all objects.

Properties

The following table lists the properties of the FPCAccounts collection.

Property | Description
Count | Retrieves the number of account objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAccounts.Add Method

Creates a new account object, inserts it into the collection, and returns a reference to it.

Syntax

[ oFPCAccount = ] FPCAccounts.Add( sAccount, iAccountStat )

Parameters

sAccount
Required. String that specifies the account. Specified in domain\account format.
iAccountStat
Required. Integer flag. Can have a value from the FpcIncludeStatus enumerated type.

Return Values

oFPCAccount
Returns a reference to the FPCAccount object.

Applies To

FPCAccounts


FPCAccounts.Count Property

Returns the number of account objects in the collection.

Syntax

[ iCount = ] FPCAccounts.Count

Possible Values

iCount
Integer value that specifies the number of FPCAccount objects.

The property is read-only.

Applies To

FPCAccounts


FPCAccounts.Item Method

Returns the given FPCAccount object from the collection.

Syntax

[ vItem = ] FPCAccounts.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve. The "name" given to specify an account is in "domain\account" format.

Return Values

vItem
If successful, returns a reference to an object of type FPCAccount. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Remarks

The vIndex parameter is in the form of an index or a name. For example, the following code

FPCAccounts.Item("africa\john")

specifies an account by name and is in "domain\account" format.

Applies To

FPCAccounts


FPCAccounts.Refresh Method

Reads all the FPCAccount objects from persistent storage, discarding any changes to the objects that were not saved.

Syntax

FPCAccounts.Refresh()

Applies To

FPCAccounts


FPCAccounts.Remove Method

Removes an account from the collection.

Syntax

FPCAccounts.Remove( iIndex )

Parameters

iIndex
Required. Name or one-based index of the FPCAccount object to remove.

Remarks

The vIndex parameter is either in the form of an index or a name. For example, the following:

FPCAccounts.Item("africa\john")

specifies an account by name and is in "domain\account" format.

Applies To

FPCAccounts


FPCAccounts.RemoveAll Method

Removes all objects from the collection.

Syntax

FPCAccounts.RemoveAll( )

Applies To

FPCAccounts


FPCActiveCacheConfiguration Object

The FPCActiveCacheConfiguration object provides access to the active cache configuration settings of an ISA Server computer. Active caching is a mechanism for automatically obtaining and caching updated content for popular sites. The objects FPCActiveCacheConfiguration, FPCHTTPCacheConfiguration, and FPCFTPCacheConfiguration provide access to all ISA cache configuration settings. These three objects are accessed through properties of the FPCCacheConfiguration object, which serves as a container for the three.

The FPCActiveCacheConfiguration object is a property of an FPCCacheConfiguration object.

Note to C++ Programmers

This object implements the IFPCActiveCacheConfiguration interface.

Methods

The following table lists the methods of the FPCActiveCacheConfiguration object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.
ResetToDefaults | Discards any changes made to the active cache configuration and reverts to the default cache configuration.
Save | Saves the active cache configuration to persistent storage.

Properties

The following table lists the properties of the FPCActiveCacheConfiguration object.

Property | Description
ActiveCachingEnable | Sets or retrieves whether active caching is enabled.
ActiveCachingPolicy | Sets or retrieves the policy for pre-fetching of popular objects into the cache.
VendorParametersSets | Retrieves a reference to an object for storing and loading of custom data into the FPCCacheConfiguration object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCActiveCacheConfiguration.ActiveCachingEnable Property

Sets or retrieves whether active caching is enabled.

Syntax

FPCActiveCacheConfiguration.ActiveCachingEnable [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Active caching is enabled.
FALSE | Active caching is disabled.

The property is read-write.

Applies To

FPCActiveCacheConfiguration


FPCActiveCacheConfiguration.ActiveCachingPolicy Property

Sets or retrieves the policy for prefetching of popular objects into the cache.

Syntax

FPCActiveCacheConfiguration.ActiveCachingPolicy [ = iPolicy ]

Possible Values

iPolicy
A value from the FPCActiveCachingPolicy enumeration.

The property is read-write.

Applies To

FPCActiveCacheConfiguration


FPCActiveCacheConfiguration.Refresh Method

Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.

Syntax

FPCActiveCacheConfiguration.Refresh()

Applies To

FPCActiveCacheConfiguration


FPCActiveCacheConfiguration.ResetToDefaults Method

Discards any changes made to the active cache configuration and reverts to the default cache configuration.

Syntax

FPCActiveCacheConfiguration.ResetToDefaults()

Applies To

FPCActiveCacheConfiguration


FPCActiveCacheConfiguration.Save Method

Saves the active cache configuration to persistent storage.

Syntax

FPCActiveCacheConfiguration.Save()

Applies To

FPCActiveCacheConfiguration


FPCActiveCacheConfiguration.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCCacheConfiguration object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCActiveCacheConfiguration.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCActiveCacheConfiguration


FPCAdapter Object

The FPCAdapter object represents a single network adapter of an ISA server. You can connect to the Internet through either a direct or dial-up connection. If you choose a direct connection, you need to set up an external network adapter. This object represents that adapter, and is a member of the the FPCAdapterList collection.

Note to C++ Programmers

This object implements the IFPCAdapter interface.

Properties

The following table lists the properties of the FPCAdapter object.

Property | Description
Description | Retrieves the name of the adapter.
IpAddresses | Retrieves a comma-delimited list of all the IP addresses bound to the adapter.
Selected | Sets or retrieves a Boolean value indicating whether this network adapter is selected to be included in the Local Address Table (LAT) construction.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAdapter.Description Property

Retrieves the name of the network adapter.

Syntax

[ sDescription = ] FPCAdapter.Description

Possible Values

sDescription
String that specifies the description of the adapter.

The property is read-only.

Applies To

FPCAdapter


FPCAdapter.IpAddresses Property

Retrieves a comma-delimited list of all IP addresses that are bound to the network adapter.

Syntax

[ sIpAddresses = ] FPCAdapter.IpAddresses

Possible Values

sIpAddresses
String that specifies the IP addresses.

The property is read-only.

Applies To

FPCAdapter


FPCAdapter.Selected Property

Sets or retrieves a Boolean value that indicates whether the network adapter is selected to be included in the Local Address Table (LAT) construction.

Syntax

FPCAdapter.Selected [ = bSelected ]

Possible Values

bSelected
Boolean value that has either of these settings:
Setting | Meaning
TRUE | This adapter is selected.
FALSE | This adapter is not selected.

The property is read-write.

Remarks

This property is used in conjunction with the FPCLAT.AddFromSelectedAdapters method to generate the LAT. The state of bSelected is not retained when the object is discarded. This means that if you use this object to set bSelected to be TRUE, then discard this object, the state of bSelected will not be stored in memory.

Applies To

FPCAdapter


FPCAdapterList Collection

The FPCAdapterList collection provides access to a group of FPCAdapter objects. You can connect to the Internet through either a direct or dial-up connection. If you choose a direct connection, you need to set up an external network adapter. This collection represents a group of adapters, and is a property of the FPCServer object.

Note to C++ Programmers

This collection implements the IFPCAdapterList interface.

Methods

The following table lists the methods of the FPCAdapterList collection.

Method | Description
Item | Retrieves the given FPCAdapter object from the collection.
Refresh | Reads all the FPCAdapter objects from storage.

Properties

The following table lists the properties of the FPCAdapterList collection.

Property | Description
Count | Retrieves the number of FPCAdapter objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAdapterList.Count Property

Retrieves the number of FPCAdapter objects in the collection.

Syntax

[ iCount = ] FPCAdapterList.Count

Possible Values

iCount
Integer value that specifies the number of FPCAdapter objects.

The property is read-only.

Applies To

FPCAdapterList


FPCAdapterList.Item Method

Retrieves the given FPCAdapter object from the collection.

Syntax

[ vItem = ] FPCAdapterList.Item( vIndex )

Parameters

vIndex
Required. IP or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCAdapter. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

This property is read-only.

Applies To

FPCAdapterList


FPCAdapterList.Refresh Method

Reads all the FPCAdapter objects from storage.

Syntax

FPCAdapterList.Refresh()

Applies To

FPCAdapterList


FPCAlert Object

The FPCAlert object defines an alert. When a specific event occurs, this object determines the actions that will be taken in response to that event. The FPCAlert object also defines the three thresholds that determine when actions will be taken. Alerts allow for an administrator to be notified when certain events take place, and to decide which actions should be taken in advance. Properties of the actions to be taken are accessed through the FPCAlertActions collection.

For a more detailed example of using the FPCAlert object, see Adding a Custom Event and Alert.

This object is a member of the FPCAlerts collection.

Note to C++ Programmers

This object implements the IFPCAlert interface.

Methods

The following table lists the methods of the FPCAlert object.

Method | Description
Refresh | Reads the FPCAlert object from persistent storage, discarding any changes to the object that were not saved.
Save | Saves the object's configuration to persistent storage.
SetDefinitions | Sets the following definitions of the alert: event GUID, server name and the additional key. The three must be set simultaneously because they should form a unique triplet.

Properties

The following table lists the properties of the FPCAlert object.

Property | Description
Actions | Returns a reference to the FPCAlertActions collection.
AdditionalKey | Returns the index to the additional key table of the event associated with this alert..
Description | Sets or returns the description of the alert object.
Enabled | Sets or returns whether the alert is enabled.
EventGUID | Returns the GUID of the event type on which the alert is based.
EventsBeforeRaise | Sets or retrieves the count of events that signals another event.
MinEventsPerSecond | Sets or returns the count of events per second that signals another event.
MinutesBeforeReRaise | Sets or returns the interval between invocations of the count of minutes that signals another event.
Name | Sets or returns the name of the alert object.
Password | Sets or returns the password for the credentials of the command-line action.
ServerName | Returns the name of the server allowed to signal this alert.
UserName | Sets or returns the user name for the credentials of the command-line action.
VendorParametersSets | Returns a reference to an object for storing and loading of custom data into the FPCAlert object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAlert.Actions Property

Returns a reference to the FPCAlertActions collection, which is a collection of FPCAlertAction objects. Each FPCAlertAction object defines an FPC action.

Syntax

[ collFPCAlertActions = ] FPCAlert.Actions

Possible Values

collFPCAlertActions
Reference to the FPCAlertActions collection.

The property is read-only.

Applies To

FPCAlert


FPCAlert.AdditionalKey Property

Returns the index to the additional-key table of the event associated with this alert.

Additional keys serve as a means to subdivide event objects into related subevents; for example, to subdivide a disk-full event into log-disk-full or system-disk-full subevents. This allows for either different alerts that are specific to subevents or one alert that is specific to all subevents.

For example, an administrator can add separate alerts for each separate subevent by specifying an EventGUID and AdditionalKey property for each subevent. The AdditionalKey property is the index used in the additional-key table. Alternatively, an administrator can treat all subevents as a singular event by specifying EventGUID and setting AdditionalKey to zero. In other words, the index zero is 'reserved' and shouldn't be overloaded with a user specific additional key.

The additional-key table cannot be modified; an administrator can only select keys from the table.

Syntax

[ iKey = ] FPCAlert.AdditionalKey

Possible Values

iKey
Integer value that specifies the index.

The property is read-only.

Applies To

FPCAlert


FPCAlert.Description Property

Sets or retrieves the description of the alert object.

Syntax

FPCAlert.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the alert object.

The property is read-write.

Applies To

FPCAlert


FPCAlert.Enabled Property

Sets or retrieves whether the alert is enabled.

Syntax

FPCAlert.Enabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Alert is enabled.
FALSE | Alert is disabled.

The property is read-write.

Applies To

FPCAlert


FPCAlert.EventGUID Property

Returns the globally unique identifier (GUID) of the event type on which the alert is based. Each event invariably has a unique GUID.

Syntax

[ sGUID = ] FPCAlert.EventGUID

Possible Values

sGUID
String that specifies the GUID.

The property is read-only.

Applies To

FPCAlert


FPCAlert.EventsBeforeRaise Property

Sets or retrieves the count of events that signals another event.

The MinutesBeforeReRaise, EventsBeforeRaise, and MinEventsPerSecond properties set the three thresholds that the alert service uses to signal alerts. For each alert, the alert service stores the last time the alert was signaled, a count of how many times the alert has been signaled per second and a count of the total number of times the alert has been signaled. An alert is given and the alert invokes the actions specific to the alert only when the three threshold requirements for signaling an alert are met simultaneously.

The EventsBeforeRaise property sets the threshold for the number of times the alert has been signaled.

Syntax

FPCAlert.EventsBeforeRaise [ = iThreshold ]

Possible Values

iThreshold
Integer that specifies the threshold.

The property is read-write.

Applies To

FPCAlert


FPCAlert.MinEventsPerSecond Property

Sets or retrieves the count of events per second that signals another event.

The MinutesBeforeReRaise, EventsBeforeRaise, and MinEventsPerSecond properties set the three thresholds that the alert service uses to signal alerts. For each alert, the alert service stores the last time the alert was signaled, a count of how many times the alert has been signaled per second and a count of the total number of times the alert has been signaled. An alert is given and the alert invokes the actions specific to the alert only when the three threshold requirements for signaling an alert are met simultaneously.

The MinEventsPerSecond property sets the threshold for the number of alerts signaled per second.

Syntax

FPCAlert.MinEventsPerSecond [ = lThreshold ]

Possible Values

lThreshold
Long value that specifies the threshold of the signaling rate or operate mode.

The property is read-write.

Applies To

FPCAlert


FPCAlert.MinutesBeforeReRaise Property

Sets or retrieves the interval between invocations of the count of minutes that signals another event.

The MinutesBeforeReRaise, EventsBeforeRaise, and MinEventsPerSecond properties set the three thresholds that the alert service uses to signal alerts. For each alert, the alert service stores the last time the alert was signaled, a count of how many times the alert has been signaled per second and a count of the total number of times the alert has been signaled. An alert is given and the alert invokes the actions specific to the alert only when the three threshold requirements for signaling an alert are met simultaneously.

The MinutesBeforeReRaise property sets the threshold for the last time the alert was signaled.

Syntax

FPCAlert.MinutesBeforeReRaise [ = iInterval ]

Possible Values

iInterval
Integer that specifies the signaling interval.

The property is read-write.

Applies To

FPCAlert


FPCAlert.Name Property

Sets or returns the name of the alert object.

Syntax

FPCAlert.Name [ = sName ]

Possible Values

sName
String that specifies the name of the alert object.

The property is read-write.

Applies To

FPCAlert


FPCAlert.Password Property

Sets or retrieves the password for the credentials of the command-line action.

The UserName and Password properties are used to restrict the privileges of commands invoked by the alert service. For example, an account could be created with appropriate privileges, and the name and password of that account could then be used by the FPCAlert object. The UserName and Password properties are used only for run-program actions.

Syntax

[ sPassword = ] FPCAlert.Password

Possible Values

sPassword
String that specifies the password.

The property is read-only.

Applies To

FPCAlert


FPCAlert.Refresh Method

Reads the FPCAlert object from persistent storage, discarding any changes to the object that were not saved.

Syntax

FPCAlert.Refresh()

Applies To

FPCAlert


FPCAlert.Save Method

Saves the object's configuration to persistent storage. Note that any changes made in scripts and programs will not be saved until after the Save method is called.

Syntax

FPCAlert.Save()

Applies To

FPCAlert


FPCAlert.ServerName Property

Returns the name of the server that is allowed to signal this alert.

Syntax

[ sName = ] FPCAlert.ServerName

Possible Values

sName
String that specifies the server name.

The property is read-only.

Applies To

FPCAlert

Remarks

When the sName parameter is an empty string, or "", the property returns all the servers, meaning that all servers are allowed to signal this alert.


FPCAlert.SetDefinitions Method

Sets the following definitions of the alert: event globally unique identifier (GUID), server name, and the additional key. The three must be set simultaneously because they form a unique triplet.

Syntax

FPCAlert.SetDefinitions( sEventGUID, sServerName, lAdditionalKey )

Parameters

sEventGUID
String that specifies the GUID of the event that triggers this alert.
sServerName
Optional. String that specifies the name of the server that is allowed to signal this alert.
lAdditionalKey
Optional. Long value of the additional key. The key is an index to a table defined in the corresponding event.

Applies To

FPCAlert


FPCAlert.UserName Property

Sets or retrieves the user name for the credentials of the command line action.

The UserName and Password properties are used to restrict the privileges of commands invoked by the alert service. For example, an account could be created with appropriate privileges, and the name and password of that account could then be used by the FPCAlert object. The UserName and Password properties are used only for run-program actions.

Syntax

[ sName = ] FPCAlert.UserName

Possible Values

sName
String that specifies the user name.

The property is read-write.

Applies To

FPCAlert


FPCAlert.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCAlert object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCAlert.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCAlert


FPCAlerts Collection

FPCAlerts is a collection of individual FPCAlert objects. Each object within this collection defines an alert. When a specific event occurs, this object determines the actions that will be taken in response to that event. The FPCAlert object also defines the three thresholds that determine when actions will be taken. Alerts allow for an administrator to be notified when certain events take place, and to decide which actions should be taken in advance.

The FPCAlerts collection is a property of the FPCArray object.

Note to C++ Programmers

This collection implements the IFPCAlerts interface.

Methods

The following table lists the methods of the FPCAlerts collection.

Method | Description
Add | Creates a new alert, inserts it into the collection, and returns a reference to it.
Item | Returns the given FPCAlert object from the collection.
Refresh | Reads all the FPCAlert objects from persistent storage, discarding any changes to the objects that were not saved.
Remove | Removes an alert from the collection.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCAlerts collection.

Property | Description
Count | Returns the number of FPCAlert objects in the collection.
VendorParametersSets | Returns a reference to an object for storing and loading custom data into the FPCAlerts collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAlerts.Add Method

Creates a new alert, inserts it into the collection, and returns a reference to it.

Syntax

[ oFPCAlert = ] FPCAlerts.Add( sName, sEventGUID, sServerName, lAdditionalKey )

Parameters

sName
Required. String that specifies the name of the alert. Can be used in FPCAlerts to retrieve the alert.
sEventGUID
Required. String that specifies the GUID of the event that triggers this alert.
sServerName
Optional. String that specifies the name of the server that is allowed to signal alerts. If no server is specified, any server is allowed to signal events.
lAdditionalKey

Optional. Long value that specifies the index to the additional-key table of this alert's event. This parameter's value should be less than or equal to the number of additional event keys. It should not be set to NULL.

Return Values

oFPCAlert
Returns a reference to the FPCAlert object.

Applies To

FPCAlerts


FPCAlerts.Count Property

Returns the number of alert objects in the collection.

Syntax

[ lCount = ] FPCAlerts.Count

Possible Values

lCount
Long value that specifies the number of FPCAlert objects.

The property is read-only.

Applies To

FPCAlerts


FPCAlerts.Item Method

Returns the given FPCAlert object from the collection.

Syntax

[ vItem = ] FPCAlerts.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCAlert. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCAlerts


FPCAlerts.Refresh Method

Reads all the FPCAlert objects from persistent storage, discarding any changes to the objects that were not saved.

Syntax

FPCAlerts.Refresh()

Applies To

FPCAlerts


FPCAlerts.Remove Method

Removes an alert from the collection.

Syntax

FPCAlerts.Remove( iIndex )

Parameters

iIndex
Required. Name or one-based index of the FPCAlert object to remove.

Applies To

FPCAlerts


FPCAlerts.Save Method

Saves the object's configuration to persistent storage.

Syntax

FPCAlerts.Save()

Applies To

FPCAlerts


FPCAlerts.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCAlerts collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCAlerts.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCAlerts


FPCAlertAction Object

The FPCAlertAction object defines a single action. Each action is carried out when an ISA alert signals that an action needs to be taken. You can determine the kind of action you want taken by using the Type property. The Type property determines whether the action will be to send mail, to issue a command, to write to a log, or another task.

This object is a member of the FPCAlertActions collection.

Note to C++ Programmers

This object implements the IFPCAlertAction interface.

Methods

The following table lists the methods of the FPCAlertAction object.

Method | Description
Refresh | Reads the object from persistent storage, discarding any changes to the object that were not saved.
Save | Saves the action's configuration to persistent storage.

Properties

The following table lists the properties of the FPCAlertAction object.

Property | Description
Enabled | Sets or retrieves whether the action is enabled.
Name | Returns the name of the alert action.
Parameters | Returns a domain array of strings that specify optional parameters for the action.
Type | Returns the type identifier (ID) of the alert action.
VendorParametersSets | Returns a reference to an object for storing and loading custom data into the FPCAlertAction object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAlertAction.Enabled Property

Sets or retrieves whether the action is enabled.

Syntax

FPCAlertAction.Enabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Alert is enabled.
FALSE | Alert is disabled.

The property is read-write.

Applies To

FPCAlertAction


FPCAlertAction.Name Property

Returns the name of the alert action.

Syntax

[ sName = ] FPCAlertAction.Name

Possible Values

sName
String that specifies the alert-action name.

The property is read-write.

Applies To

FPCAlertAction


FPCAlertAction.Parameters Property

Returns a domain array of strings that specify optional parameters for an action.

Syntax

[ sParameters  = ] FPCAlertAction.Parameters

Possible Values

sParameters
Array of strings that specifies optional parameters.

The property is read-only.

Remarks

The following table shows the values of sParameters.

Action | param1 | param2 | param3 | param4
log event | none | none | none | none
command | command line | none | none | none
stop/start service | service name | service name | service name | service name
send mail | SERVER= x (1) | TO= x (2) | CC= x (3) | FROM= x (4)
(1) - x is a list of SMTP mail servers, space delimited (2) - x is a list of To recipients, space delimited (3) - x is a list of Cc recipients, space delimited (4) - x is a list of From recipients, space delimited

Applies To

FPCAlertAction


FPCAlertAction.Refresh Method

Reads the object from persistent storage, discarding any changes to the object that were not saved.

Syntax

FPCAlertAction.Refresh()

Applies To

FPCAlertAction


FPCAlertAction.Save Method

Saves the action's configuration to persistent storage.

Syntax

FPCAlertAction.Save()

Applies To

FPCAlertAction


FPCAlertAction.Type Property

Returns the type identifier (ID) of the alert action. You can use this property to determine specifically what this action does.

Syntax

[ ActionType = ] FPCAlertAction.Type

Possible Values

ActionType
Action type identifier (ID). It can have a value from the FpcActionTypes enumerated type.

The property is read-only.

Applies To

FPCAlertAction


FPCAlertAction.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCAlertAction object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCAlertAction.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCAlertAction


FPCAlertActions Collection

The FPCAlertActions collection accesses a group of FPCAlertAction objects. Each object in this collection defines an action. This actions are carried out when an ISA alert signals that an action needs to be taken.

FPCAlertActions is a property of the FPCAlert object.

Note to C++ Programmers

This collection implements the IFPCAlertActions interface.

Methods

The following table lists the methods of the FPCAlertActions collection.

Method | Description
Item | Retrieves the given FPCAlertAction object from the collection.
Refresh | Reads all the FPCAlertAction objects from persistent storage, discarding any changes to the objects that were not saved.
Save | Saves the configuration of all FPCAlertAction objects to persistent storage.
SetCommand | Creates a new command-line action in the collection, or updates the command-line action if it already exists.
SetLogEvent | Creates a new log-event action in the collection, or updates the log-event action if it already exists.
SetSendMail | Creates a new send-mail action in the collection, or updates the send-mail action if it already exists.
SetStartServices | Creates a new start-services action in the collection, or updates the start-services action if it already exists.
SetStopServices | Creates a new stop-services action in the collection, or updates the stop-services action if it already exists.
Unset | Sets the action specified to a disabled state.

Properties

The following table lists the properties of the FPCAlertActions collection.

Property | Description
Count | Retrieves the number of FPCAlertAction objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCAlertActions collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAlertActions.Count Property

Retrieves the number of alert action objects in the collection.

Syntax

[ lCount = ] FPCAlertActions.Count

Possible Values

lCount
Long value that specifies the number of FPCAlertAction objects.

The property is read-only.

Applies To

FPCAlertActions


FPCAlertActions.Item Method

Retrieves the given FPCAlertAction object from the collection.

Syntax

[ vItem = ] FPCAlertActions.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCAlertAction. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCAlertActions


FPCAlertActions.Refresh Method

Reads all the FPCAlertAction objects from persistent storage, discarding any changes to the objects that were not saved.

Syntax

FPCAlertActions.Refresh()

Applies To

FPCAlertActions


FPCAlertActions.Save Method

Saves the configuration of all FPCAlertAction objects in the collection to persistent storage.

Syntax

FPCAlertActions.Save()

Applies To

FPCAlertActions


FPCAlertActions.SetCommand Method

Creates a new command-line action in the collection, or updates the command-line action if it already exists.

Syntax

[ oFPCAlertAction = ] FPCAlertActions.SetCommand( sActionName, sCommand )

Parameters

sActionName
Required. String that specifies the name of the action. Can be used in the FPCAlertActions collection to retrieve the action.
sCommand
Required. String that specifies the command line action.

Return Values

oFPCAlertAction
Returns a reference to an FPCAlertAction object for the new or updated command-line action.

Applies To

FPCAlertActions


FPCAlertActions.SetLogEvent Method

Creates a new log-event action in the collection, or updates the log-event action if it already exists.

Syntax

[ oFPCAlertAction = ] FPCAlertActions.SetLogEvent( sActionName )

Parameters

sActionName
Required. String that specifies the name of the action. Can be used to retrieve the action.

Return Values

oFPCAlertAction
Returns a reference to the FPCAlertAction object for the new or updated log-event action.

Applies To

FPCAlertActions


FPCAlertActions.SetSendMail Method

Creates a new send-mail action in the collection, or updates the send-mail action if it already exists.

Syntax

[ oFPCAlertAction = ] FPCAlertActions.SetSendMail( sActionName, sServer, sToField, sCcField, sFromField )

Parameters

sActionName
Required. String that specifies the name of the action. Can be used to retrieve the action.
sServer
Required. String that specifies a space-delimited list of SMTP servers.
sToField
Required. String that specifies a space-delimited list of mail recipients that appear on the To: list.
sCcField
Required. String that specifies a space-delimited list of mail recipients that appear on the CC: list.
sFromField
Required. String that specifies a space-delimited list of mail recipients that appear on the From: list.

Return Values

oFPCAlertAction
Returns a reference to the FPCAlertAction object for the new or updated send-mail action.

Applies To

FPCAlertActions


FPCAlertActions.SetStartServices Method

Creates a new start-services action in the collection, or updates the start-services action if it already exists.

Syntax

[ oFPCAlertAction = ] FPCAlertActions.SetStartServices( sActionName, iServices )

Parameters

sActionName
Required. String that specifies the name of the action. Can be used to retrieve the action.
iServices
Required. Integer value that specifies which services will be started. It can have a value from the FpcServices enumerated type.

Return Values

oFPCAlertAction
Returns a reference to an FPCAlertAction object for the new or updated start-services action.

Applies To

FPCAlertActions


FPCAlertActions.SetStopServices Method

Creates a new stop-services action in the collection, or updates the stop-services action if it already exists.

Syntax

[ oFPCAlertAction = ] FPCAlertActions.SetStopServices( sActionName, iServices )

Parameters

sActionName
Required. String that specifies the name of the action. Can be used to retrieve the action.
iServices
Required. Integer that specifies which FPC services will be stopped. It can have a value from the FpcServices enumerated type.

Return Values

oFPCAlertAction
Returns a reference to an FPCAlertAction object for the new or updated stop-services action.

Applies To

FPCAlertActions


FPCAlertActions.Unset Method

Sets the action specified to a disabled state.

Syntax

FPCAlertActions.Unset( ActionType )

Parameters

ActionType
Required. Specifies the action type to be unset. It can have a value from the FpcActionTypes enumerated type.

Applies To

FPCAlertActions


FPCAlertActions.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCAlertActions collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCAlertActions.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCAlertActions


FPCAlertInfo Object

The FPCAlertInfo object represents information about a signaled alert. The information stored in this object can be retrieved all at once by using the GetAllProperties method. To reset ISA to signal an alert associated with this object, use the EventGUID, ServerName, and AdditionalKey properties. Use the values of these three properties in a call to the FPCAlertNotification.ResetNotificationState method.

The FPCAlertInfo object is created with a statement such as the following:

Dim FPCAlertInfo as new ALERTSRVLib.AlertInfo

Note to C++ Programmers

This object implements the IFPCAlertInfo interface.

Methods

The following table lists the methods of the FPCAlertInfo object.

Method | Description
GetAllProperties | Returns all properties of the FPCAlertInfo object at once.

Properties

The following table lists the properties of the FPCAlertInfo object.

Property | Description
AdditionalKey | Returns the additional key of the alert.
Description | Returns the description of the alert.
EventGUID | Returns the globally unique identifier (GUID) of the event that signaled the alert.
FirstSignalTime | Returns a DATE data type of the time of the first alert signaling (in GMT).
Name | Returns the name of the alert.
ServerName | Returns either the name of the current server, or an empty string representing an alert from all ISA servers.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Alertsrv.idl.


FPCAlertInfo.AdditionalKey Property

Returns the additional key of the alert. The additional key will be one of the following: (-1), which represents no additional keys; (0), which represents any additional keys; or the actual value of an individual additional key.

Syntax

[ lAdditionalKey = ] FPCAlertInfo.AdditionalKey

Return Values

lAdditionalKey
Long value that specifies the additional key of the alert.

This property is read only.

Applies To

FPCAlertInfo


FPCAlertInfo.Description Property

Returns the description of the alert.

Syntax

[ sDescription = ] FPCAlertInfo.Description

Return Values

sDescription
String that specifies the description of the alert.

This property is read only.

Applies To

FPCAlertInfo


FPCAlertInfo.EventGUID Property

Returns the globally unique identifier (GUID) of the event that signaled the alert.

Syntax

[ sEventGUID = ] FPCAlertInfo.EventGUID

Return Values

sEventGUID
String that specifies the GUID of the event that signaled the alert.

This property is read only.

Applies To

FPCAlertInfo


FPCAlertInfo.FirstSignalTime Property

Returns a DATE value of the time of the first signaling of the alert in system time (AKA, UTC, or GMT).

Syntax

[ dFirstSignalTime = ] FPCAlertInfo.FirstSignalTime

Return Values

dFirstSignalTime
DATE value of the first signaling of the alert.

This property is read only.

Applies To

FPCAlertInfo


FPCAlertInfo.GetAllProperties Method

Returns all the properties of the FPCAlertInfo object at once.

Syntax

FPCAlertInfo.GetAllProperties( sEventGuid, sServerName,
lAdditionalKey, sName, sDescription, FirstSignalTime)

Parameters

sEventGuid
[out] String that specifies the globally unique identifier (GUID) of the event that signaled the alert.
sServerName
[out] String that specifies the server name.
lAdditionalKey
[out] Long value that specifies the additional key.
sName
[out] String that specifies the name of the alert.
sDescription
[out] String that specifies the description of the alert.
FirstSignalTime
[out] DATE value that specifies the system time of the first signaling of the alert.

Applies To

FPCAlertInfo


FPCAlertInfo.Name Property

Returns the name of the alert.

Syntax

[ sName = ] FPCAlertInfo.Name

Return Values

sName
String that specifies the name of the alert.

This property is read only.

Applies To

FPCAlertInfo


FPCAlertInfo.ServerName Property

Returns the name of the ISA server for which the alert is defined, or an empty string representing an alert that applies to all servers within an array.

Syntax

[ sServerName = ] FPCAlertInfo.ServerName

Return Values

sServerName
String that specifies the name of the server that issued the alert.

This property is read only.

Applies To

FPCAlertInfo


FPCAlertNotification Object

The FPCAlertNotification object is the COM interface to ISA's alert service, and is used to signal an event or reset an alert's state. The alert service is responsible for recording information about events reported by ISA services, and for executing actions triggered by each event.

It is possible to enumerate all signaled alerts for a server using this object.

The FPCAlertNotification object is created with a statement such as the following:

Dim FPCAlertNotification as new ALERTSRVLib.AlertNotification

Note to C++ Programmers

This object implements the IFPCAlertNotification interface.

Methods

The following table lists the methods of the FPCAlertNotification object.

Method | Description
EnumSignaledAlerts | Returns a variant containing a domain array of variants. Each entry in the variant array contains an interface to an FPCAlertInfo object.
ResetNotificationState | Resets the notification state of the designated alert.
SignalEvent | Signals an event.
Signal_N_Events | Signals n instances of an event.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Alertsrv.idl.


FPCAlertNotification.EnumSignaledAlerts Method

Returns a variant containing a domain array of variants. Each entry in the variant array contains an interface to an FPCAlertInfo object.

Syntax

[ Variant = ] FPCAlertNotification.EnumSignaledAlerts

Possible Values

Variant
A domain array of variants.

Applies To

FPCAlertNotification


FPCAlertNotification.ResetNotificationState Method

Resets the notification state of the designated alert. This method should be used to reset the threshold information of an alert collected by the alert service until the present time. ResetNotificationState is required for alerts that execute their action only once before the administrator manually resets them. For more information about alerts, see the ISA Server product documentation.

Syntax

FPCAlertNotification.ResetNotificationState( sServerName )

Parameters

sServerName
Required. String that specifies the name of the server triggering this alert.

Applies To

FPCAlertNotification


FPCAlertNotification.SignalEvent Method

ISA services use this method to signal an event, as a part of the alert service. If an alert exists for the event and the event is in a state where it can trigger an alert, actions will be taken to notify the event. Third-party filters can also use this method to signal an event.

Syntax

FPCAlertNotification.SignalEvent( sGuid, sServerName, lAdditionalKey,
  sShortDesc, sLongDesc, lEventID, sEventSource, varEventStrings,
  varEventData, shEventCategory, shEventType)

Parameters

sGuid
Required. String that specifies the globally unique identifier (GUID) of the event triggering this alert.
sServerName
Required. String that specifies the name of the server triggering this alert.
lAdditionalKey
Required. Long that contains the index to additional keys' table for this event.
sShortDesc
String that contains a brief description of the run-time event.
sLongDesc
String that contains a detailed description of the run-time event.
lEventID
Long that contains the identifier (ID) of the event to be reported to the system event log.
sEventSource
String that contains source name for the event reported.
varEventStrings
Variant that contains insertion strings for the event reported.
varEventData
Variant that contains raw data for the event reported.
shEventCategory
Short that contains category of the event reported.
shEventType
Short that contains type of the event reported.

Applies To

FPCAlertNotification


FPCAlertNotification.Signal_N_Events Method

Used by ISA services to signal n instances of an event, as part of the alert service. If an alert exists for the event and the event is in a state where it can trigger an alert, actions will be taken to notify the event. Third-party application filters can also use this method to signal instances of an event.

Syntax

FPCAlertNotification.Signal_N_Events( sGuid, sServerName, lAdditionalKey, lEventsCount,
  sShortDesc, bstrLongDesc, lEventID, sEventSource, varEventStrings,
  varEventData, shEventCategory, shEventType)

Parameters

sGuid
Required. String that specifies the globally unique identifier (GUID) of the event triggering this alert.
sServerName
Required. String that specifies the name of the server triggering this alert.
lAdditionalKey
Required. Index to additional keys' table for this event.
lEventsCount
Required. Counts the number of instances of the event.sShortDesc
Required. String that contains a brief description of the run-time event.sLongDesc
Required. String that contains a detailed description of the run-time event.
lEventID
Required. Long that contains the identifier (ID) of the event to be reported to the system event log.
sEventSource
Required. String that contains source name for the event reported.
varEventStrings
Required. Variant that contains insertion strings for the event reported.
varEventData
Required. Variant that contains raw data for the event reported.
shEventCategory
Required. Short that contains category of the event reported.
shEventType
Required. Short that contains type of the event reported.

Note When you use the Signal_N_Events method, you must keep track of the time in which the n instances take place because the alert service assumes that the n instances all occurred at the last second. This differs from the SignalEvent, in which the alert service tracks the time.

Applies To

FPCAlertNotification


FPCApplicationFilter Object

The FPCApplicationFilter object represents a single application filter. Application filters work with the Firewall service to intercept and process data. Application filters can access the data stream or datagrams associated with a session within the Firewall service. The filters are registered with the Firewall service and act in response to events detected by the service. An application filter can perform protocol-specific or system-specific tasks, such as authentication and checking for viruses.

The FPCApplicationFilter object is a member of the FPCApplicationFilters collection.

Note to C++ Programmers

This object implements the IFPCApplicationFilter interface.

Methods

The following table lists the methods of the FPCApplicationFilter object.

Method | Description
Refresh | Reads the application filter's private data from persistent storage.
Save | Saves the application filter's private data to persistent storage.

Properties

The following table lists the properties of the FPCApplicationFilter object.

Property | Description
Description | Sets or retrieves the vendor-supplied description of the application filter.
Enabled | Sets or retrieves whether the application filter is enabled.
Guid | Retrieves the globally unique identifier (GUID) that identifies the application filter. The vendor of the filter provides the GUID.
Name | Sets or retrieves the vendor-supplied name of the application filter.
Protocols | Retrieves a collection of the application filter protocols.
Vendor | Sets or retrieves the name of the vendor of the application filter.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCApplicationFilter object's storage.
Version | Sets or retrieves the vendor-supplied version of the application filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCApplicationFilter.Description Property

Sets or retrieves the vendor-supplied description of the application filter.

Syntax

FPCApplicationFilter.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the vendor-supplied description.

The property is read-write.

Applies To

FPCApplicationFilter


FPCApplicationFilter.Enabled Property

Sets or retrieves whether the application filter is enabled.

Syntax

FPCApplicationFilter.Enabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of two settings:
Setting | Meaning
TRUE | Application filter is enabled.
FALSE | Application filter is disabled.

The property is read-write.

Note

When you've changed a setting by using the Enabled property, and save the change using the Save method, the firewall service must be restarted in order for your change to take effect. To stop and restart the firewall service use the FPCArray.SendRestartNotification Method.

Applies To

FPCApplicationFilter


FPCApplicationFilter.Guid Property

Retrieves the globally unique identifier (GUID) that identifies the application filter. The vendor of the filter provides the GUID.

Syntax

[ sGuid = ] FPCApplicationFilter.Guid

Possible Values

sGuid
String that specifies the GUID for the application filter.

The property is read-only.

Applies To

FPCApplicationFilter


FPCApplicationFilter.Name Property

Sets or retrieves the vendor-supplied name of the application filter.

Syntax

FPCApplicationFilter.Name [ = sName ]

Possible Values

sName
String that specifies the vendor-supplied name.

The property is read-write.

Applies To

FPCApplicationFilter


FPCApplicationFilter.Protocols Property

Retrieves a collection of application filter protocols.

Syntax

[ collFPCFilterProtocols = ] FPCApplicationFilter.Protocols

Possible Values

collFilterProtocols
Reference to the FPCFilterProtocols collection.

The property is read-only.

Applies To

FPCApplicationFilter


FPCApplicationFilter.Refresh Method

Reads the application filter's private data from persistent storage.

Syntax

FPCApplicationFilter.Refresh()

Applies To

FPCApplicationFilter


FPCApplicationFilter.Save Method

Saves the application filter's private data to persistent storage.

Syntax

FPCApplicationFilter.Save()

Applies To

FPCApplicationFilter


FPCApplicationFilter.Vendor Property

Sets or retrieves the name of the vendor of the application filter.

Syntax

FPCApplicationFilter.Vendor [ = sVendor ]

Possible Values

sVendor
String that specifies the vendor's name.

The property is read-write.

Applies To

FPCApplicationFilter


FPCApplicationFilter.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCApplicationFilter object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCApplicationFilter.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCApplicationFilter


FPCApplicationFilter.Version Property

Sets or retrieves the vendor-supplied version of the application filter.

Syntax

FPCApplicationFilter.Version [ = sVersion ]

Possible Values

sVersion
String that specifies the vendor-supplied version.

The property is read-write.

Applies To

FPCApplicationFilter


FPCApplicationFilters Collection

This collection provides access to all application filters, stored as FPCApplicationFilter objects. Each FPCApplicationFilter object represents a single application filter.

This object is a property of an FPCArray object.

Note to C++ Programmers

This collection implements the IFPCApplicationFilters interface.

Methods

The following table lists the methods of the FPCApplicationFilters collection.

Method | Description
Add | Adds a new FPCApplicationFilter object.
Item | Retrieves the given FPCApplicationFilter object from the collection.
Refresh | Reads all the application filter objects from persistent storage.
Remove | Removes an application filter object from the collection.
Save | Saves the application filters' private data to persistent storage.

Properties

The following table lists the properties of the FPCApplicationFilters collection.

Property | Description
Count | Retrieves the number of application filter objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCApplicationFilters collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCApplicationFilters.Add Method

Adds a new FPCApplicationFilter object to the collection, and returns a reference to it.

Syntax

[ oFPCApplicationFilter = ] FPCApplicationFilters.Add( sGuid, sName )

Parameters

sGuid
Required. String that specifies the GUID of the new application filter.
sName
Required. String that specifies the display name of the new application filter.

Return Value

oFPCApplicationFilter
Reference to an FPCApplicationFilter object.

Note

When you've added an application filter, and have saved changes by using the Save method, the firewall service must be restarted in order for your change to take effect. To stop and restart the firewall service use the FPCArray.SendRestartNotification Method.

Applies To

FPCApplicationFilters


FPCApplicationFilters.Count Property

Retrieves the number of application filter objects in the collection.

Syntax

[ iCount = ] FPCApplicationFilters.Count

Possible Values

iCount
Integer value that specifies the number of application filter objects.

The property is read-only.

Applies To

FPCApplicationFilters

See Also

FPCApplicationFilter


FPCApplicationFilters.Item Method

Retrieves the given FPCApplicationFilter object from the collection.

Syntax

[ vItem = ] FPCApplicationFilters.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCApplicationFilter. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCApplicationFilters


FPCApplicationFilters.Refresh Method

Reads all the application filter objects from persistent storage.

Syntax

FPCApplicationFilters.Refresh()

Applies To

FPCApplicationFilters


FPCApplicationFilters.Remove Method

Removes a application filter object from the collection.

Syntax

FPCApplicationFilters.Remove( vIndex )

Parameters

vIndex
Required. Globally unique identifier (GUID) or one-based index of the object to remove.

Note

When you've removed an application filter, and have saved changes by using the Save method, the firewall service must be restarted in order for your change to take effect. To stop and restart the firewall service use the FPCArray.SendRestartNotification Method.

Applies To

FPCApplicationFilters

See Also

FPCApplicationFilter


FPCApplicationFilters.Save Method

Saves the application filters' private data to persistent storage.

Syntax

FPCApplicationFilters.Save()

Applies To

FPCApplicationFilters


FPCApplicationFilters.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCApplicationFilters collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCApplicationFilters.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCApplicationFilters


FPCArray Object

The FPCArray object defines a single ISA array. An ISA array is a group of one or more ISA servers that are treated and administered as a single, logical entity. Each array has multiple configurable properties.

See ISA Administration Scripting for examples using the FPCArray object.

This object is a member of the FPCArrays collection.

Note to C++ Programmers

This object implements the IFPCArray interface.

Methods

The following table lists the methods of the FPCArray object.

Method | Description
Backup | Backs up the array configuration to a file.
GetSecurityDescriptor | Gets the security descriptor for the array.
Refresh | Reads the array's information from persistent storage, discarding any changes to the current array that were not saved.
Restore | The Restore method reads the array's information from a file.
Save | Saves the array configuration to persistent storage.
SendRestartNotification | Gets a list of services that must be restarted and sets a flag under each server for each service that should be restarted.
SetSecurityDescriptor | Sets the security descriptor for the array.

Properties

The following table lists the properties of the FPCArray object.

Property | Description
Alerts | Returns a collection of all alerts in the array.
ArrayPolicy | Returns an object holding all array policyconfiguration for this array.
BackupArrayName | Reads the array's name from the backup file.
BackupComment | Reads the backup comment from a file.
BandwidthRules | Retrieves a collection of all bandwidth rules in this array.
Cache | Returns an object holding all cache configuration for this array.
Components | Returns a set of flags indicating the components that are installed in this array.
CreatedTime | Returns a DATE data type that specifies the creation time of the object.
Description | Sets or returns the description of the array in the form of a string.
DomainName | Retrieves the array's domain name.
Extensions | Returns an FPCExtensions object.
LastModifiedTime | Returns a DATE data type that specifies the last modification time of the object.
Logging | Returns an object holding all log configuration for this array.
Name | Sets or returns the name of the array.
NetworkConfiguration | Returns an object holding all network configuration for this array.
PolicyElements | Returns an object holding all policy configuration for this array.
ProxyClientConfig | Returns a proxy-client configuration object relevant to this array.
Publishing | Returns a reference to this array's publishing configuration object.
Servers | Returns a collection of all ISA servers in this array.
SiteName | Retrieves the FPCArray object's site name.
Type | Retrieves the array's type.
VendorParametersSets | Returns a reference to an object for storing and loading custom data into the FPCArray object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCArray.Alerts Property

Returns a collection of all alerts in the array. Use this property to read, write, add, delete, or modify the Alerts property for a particular array.

Syntax

[ collFPCAlerts = ] FPCArray.Alerts

Possible Values

collFPCAlerts
Reference to an FPCAlerts collection.

The property is read-only.

Example

The following code uses the Alerts property to return the name of an individual alert:

Dim objFPC As New FPCLib.FPC
Dim alertName As String
Dim objFPCArray As FPCArray
Set objFPCArray = objFPC.Arrays(1)
alertName = objFPCArray.Alerts(1).Name

Applies To

FPCArray

See Also

FPCAlert


FPCArray.ArrayPolicy Property

Returns an object that holds the array policy information for this array.

Syntax

[ oFPCArrayPolicy = ] FPCArray.ArrayPolicy

Possible Values

oFPCArrayPolicy
Reference to an FPCArrayPolicy object.

The property is read-only.

Applies To

FPCArrayPolicy


FPCArray.Backup Method

Backs up the array configuration to a file.

Syntax

FPCArray.Backup( sFileName, sComment, bOverwrite, bValidate )

Parameters

sFileName
A string that specifies the name of the file that will contain a copy of the array information after the operation is complete.
sComment
Optional. A string that specifies a comment that can be added to the backup file.
bOverwrite
Optional. A Boolean value that specifies whether to allow an operation to continue when a backup file with the same name already exists.
bValidate
Optional. A Boolean value that specifies whether to validate the consistency of the backup file after completion of the backup operation. Not supported in this release

Applies To

FPCArray


FPCArray.BackupArrayName Property

Reads the array's name from a backup file.

Syntax

[ sArrayName = ] FPCArray.BackupArrayName( sFileName )

Possible Values

sFileName
A string that specifies the name of the file that contains a backup of the array information.

Return Values

sArrayName
Reference to a string that specifies the array name.

The property is read-only.

Applies To

FPCArray


FPCArray.BackupComment Property

Reads the backup comment from a file.

Syntax

[ sComment = ] FPCArray.BackupComment ( sFileName )

Possible Values

sFileName
A string that specifies the name of the file that contains a backup of the array information.

Return Values

sComment
Reference to a string that contains the backup comment.

The property is read-only.

Applies To

FPCArray


FPCArray.BandwidthRules Property

Retrieves a collection of all bandwidth rules in the array.

Syntax

[ collFPCBandwidthRules = ] FPCArray.BandwidthRules

Possible Values

collFPCBandwidthRules
Reference to an FPCBandwidthRules collection.

Applies To

FPCArray


FPCArray.Cache Property

Returns an object holding all cache configuration for this array. It is through this object that such properties of the FPCCache object as CacheConfiguration and CacheContents can be used to adjust cache settings.

Syntax

[ oFPCCache = ] FPCArray.Cache

Possible Values

oFPCCache
Reference to an FPCCache object.

This property is read-only.

Applies To

FPCArray


FPCArray.Components Property

Returns a set of flags indicating the components that are installed in this array.

Syntax

[ iComponents = ] FPCArray.Components

Possible Values

iComponents
Integer that specifies the component flags.

The property is read-only.

Applies To

FPCArray


FPCArray.CreatedTime Property

Returns a DATE data type that specifies the creation time of the object.

Syntax

[ dCreatedTime = ] FPCArray.CreatedTime

Possible Values

dCreatedTime
Reference to the DATE data type.

The property is read-only.

Applies To

FPCArray


FPCArray.Description Property

Sets or retrieves the description of the array. The description is stored as a string.

Syntax

FPCArray.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the array.

The property is read-write.

Applies To

FPCArray


FPCArray.DomainName Property

Retrieves the FPCArray object's domain name.

Syntax

[ sDomainName = ] FPCArray.DomainName

Return Values

sDomainName
Reference to a string that specifies the FPCArray object's domain name.

Applies To

FPCArray


FPCArray.Extensions Property

Returns an FPCExtensions object.

Syntax

[ oFPCExtensions = ] FPCArray.Extensions

Possible Values

oFPCExtensions
Reference to an FPCExtensions object.

Applies to

FPCEnterprise


FPCArray.GetSecurityDescriptor Method

Gets the security descriptor for the array. For more information see the FPCSecurityDescriptor object.

Syntax

FPCArray.GetSecurityDescriptor( lSecurityInfo, bBinary, scope )

Parameters

lSecurityInfo
Long value that specifies security information. For more information, see GetSecurityInfo in MSDN.
bBinary
Boolean value that determines whether you get the security descriptor in binary form.
scope
Specifes whether the security descriptor is for an array, for signaled alert sessions, or for sessions . It can have the value fpcSingleArrayScope, fpcAlertsScope, or fpcSessionsScope from the FPCSecurityScope enumerated type.

This property is read-write.

Remarks

This method makes use of related Windows functionality. For more information, see GetSecurityInfo in MSDN.

Applies to

FPCEnterprise


FPCArray.LastModifiedTime Property

Returns a DATE data type that specifies the last modification time of the object.

Syntax

[ dLastModifiedTime = ] FPCArray.LastModifiedTime

Possible Values

dLastModifiedTime
Reference to the DATE data type.

The property is read-only.

Applies To

FPCArray


FPCArray.Logging Property

Returns an object holding all log configurations for this array.

Syntax

[ collFPCLogs = ] FPCArray.Logging

Possible Values

collFPCLogs
Reference to an FPCLogs collection.

This property is read-only.

Applies To

FPCArray


FPCArray.Name Property

Sets or retrieves the name of the array. The name of the array is stored as a string.

Syntax

FPCArray.Name [ = sName ]

Possible Values

sName
String that specifies the array name.

The property is read-write.

Applies To

FPCArray


FPCArray.NetworkConfiguration Property

Returns an object holding all network configuration settings for this array. You can access and manipulate network configurations through this property.

Syntax

[ oFPCNetConfig = ] FPCArray.NetworkConfiguration

Possible Values

oFPCNetConfig
Reference to an FPCNetworkConfiguration object.

This property is read-only.

Applies To

FPCArray


FPCArray.PolicyElements Property

Returns an object that holds all policy configuration for this array. The FPCPolicyElements object itself has many properties that allow you to access important ISA settings — for example, configuration details, all scheduling information, destination sets, client address sets, protocol definitions, all filtering information, and all bandwidth class information. All these settings can be programmatically accessed through the PolicyElements property.

Syntax

[ oFPCPolicyElements = ] FPCArray.PolicyElements

Possible Values

oFPCPolicyElements
Reference to an FPCPolicyElements object.

This property is read-only.

Example

The following Visual Basic code example uses the PolicyElements property to list the number of schedules within an array:

Dim objFPC As New FPCLib.FPC
Dim objFPCArray As FPCArray
Dim NumSchedules As Integer
Set objFPCArray = objFPC.Arrays(1)
NumSchedules = objFPCArray.PolicyElements.Schedules.Count

Applies To

FPCArray


FPCArray.ProxyClientConfig Property

Returns a proxy client configuration object relevant to this array. Proxy client configuration settings are manipulated through this property.

Syntax

[ oProxyClientConfig = ] FPCArray.ProxyClientConfig

Possible Values

oProxyClientConfig
Reference to an FPCProxyClientConfig object.

This property is read-only.

Applies To

FPCArray


FPCArray.Publishing Property

Returns a reference to the array's publishing configuration object.

Syntax

[ oFPCPublishing = ] = FPCArray.Publishing

Possible Values

oFPCPublishing
A reference to an FPCPublishing object.

The property is read-only.

Applies To

FPCArray


FPCArray.Refresh Method

Reads the array's information from persistent storage, and discards any changes to the current array that were not saved.

Syntax

FPCArray.Refresh()

Applies To

FPCArray


FPCArray.Restore Method

Reads the array's information from a file.

Syntax

FPCArray.Restore( sFileName, bValidate, bRestoreUnusedServers, bKeepNewServers )

Parameters

sFileName
A string that specifies the name of the file that contains a backup of the array information. The restore operation will copy the information in that file to the current array.
bValidate
Optional. A Boolean value that specifies whether to validate the consistency of the restored array aftter the completion of the restore operation. Not supported in this release bRestoreUnusedServers

Optional. A Boolean value that specifies whether to restore the configuration of servers that were found in the backup file and not in the current array.

bKeepNewServers
Optional. A Boolean value that specifies whether to delete server configurations that are found in the current array and not in the backup file.

Applies To

FPCArray


FPCArray.Save Method

Saves the array configuration to persistent storage. It is important to remember that any changes made in scripts and programs will not be saved unless the Save method is called.

Syntax

FPCArray.Save()

Applies To

FPCArray


FPCArray.SendRestartNotification Method

Gets a list of services that must be restarted and sets a flag under each server for each service to be restarted. The ISA control service reacts to these flags and restarts the affected service when they change. You can use this method to restart the firewall service, the w3proxy service, or both.

Syntax

FPCArray.SendRestartNotification( Services )

Parameters

Services
Specifies the services to be restarted. Can have a value from the FpcServices enumerated type.

The property is read-only.

Applies To

FPCArray


FPCArray.Servers Property

Returns a collection of all ISA servers in this array. This property can be used in turn to access all the properties of each individual server.

Syntax

[ collFPCServers = ] FPCArray.Servers

Possible Values

collFPCServers
Reference to an FPCServers collection.

The property is read-only.

Example

The following code uses the Servers property to return the name of an individual server.

Dim objFPC As New FPCLib.FPC
Dim serverName As String
Dim objFPCArray As FPCArray
Set objFPCArray = objFPC.Arrays(1)
serverName = objFPCArray.Servers(1).Name

Applies To

FPCArray

See Also

FPCServer


FPCArray.SetSecurityDescriptor Method

Sets the security descriptor for the array. For more information see the FPCSecurityDescriptor object.

Syntax

FPCArray.SetSecurityDescriptor( lSecurityInfo, scope )

Parameters

lSecurityInfo
Long value that specifies security information.
scope
Specifes whether the security descriptor is for an array, for a signaled alert session, or for sessions . It can have the value fpcSingleArrayScope, fpcAlertsScope, or fpcSessionsScope from the FPCSecurityScope enumerated type.

This property is read-only.

Remarks

This method makes use of related Windows functionality. For more information, see SetSecurityInfo in MSDN.

Applies To

FPCArray


FPCArray.SiteName Property

Retrieves the FPCArray object's site name.

Syntax

[ sSite = ] FpcArray.SiteName

Possible Values

sSite
String that specifies the FPCArray object's site name.
This property is read-only.

Applies To

FPCArray


FPCArray.Type Property

Retrieves the array's type.

Syntax

[ Type = ] FPCArray.Type

Possible Values

Type
Retrieves the array type This can have a value from the FpcArrayType enumerated type.

Applies To

FPCArray


FPCArray.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCArray object's storage. The VendorParametersSets property allows third-party extensions to be integrated into ISA.

Syntax

[ collFPCVendorParametersSets = ] FPCArray.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCArray


FPCArrays Collection

The FPCArrays collection provides access to a collection of FPCArray objects. Individual servers and individual server properties are accessed through each FPCArray object.

See ISA Administration Scripting for multiple examples of using the FPCArrays collection.

FPCArrays is a property of the FPC root object.

Note to C++ Programmers

This collection implements the IFPCArrays interface.

Methods

The following table lists the methods of the FPCArrays collection.

Method | Description
Add | Adds a new array to the collection.
CurrentArray | Returns the current containing array.
Item | Returns the array object specified by the integer parameter of this method.
Refresh | Refreshes all the properties of the object, returning them to the values they held when the object was first created.
Remove | Removes the array collection.
Save | Saves the current object values. This method must be called to save any changes to persistent storage.

Properties

The following table lists the properties of the FPCArrays collection.

Property | Description
Count | Returns the number of array objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCArrays.Add Method

Adds a new array to the collection.

Syntax

FPCArrays.Add( sDomainName, sSiteName, lComponents, ArrayToClone )

Parameters

sDomainName
Optional. String that specifies the domain name in which to create the array.
sSiteName
Required. Name of FPCArray object to add.
lComponents
Long value that specifies the array components.
ArrayToClone
Optional. Array name from which to copy the configuration.

Applies To

FPCArrays Collection


FPCArrays.Count Property

Returns the number of array objects within the FPCArrays collection.

Syntax

[ iCount = ] FPCArrays.Count

Possible Values

iCount
Integer value that specifies the number of FPCArray objects.

The property is read-only.

Applies To

FPCArrays


FPCArrays.CurrentArray Method

Returns the array that contains the current computer. Assume, for example, that there are two arrays, Arr1 and Arr2. Arr1 contains two computers, a and b. Arr2 contains computer c. If you call CurrentArray on computer a, the method will return Arr1. If you call CurrentArray on computer c, the method will return Arr2.

Syntax

[ oFPCArray = ] FPCArrays.CurrentArray()

Possible Values

oFPCArray
Reference to the containing FPCArray object.

Example

The following snippet of code retrieves the name of the current containing array by means of the CurrentArray method.

Dim objFPC As New FPCLib.FPC
Dim CurrentArray As String
Dim objFPCArrays As FPCArrays
Set objFPCArrays = objFPC.Arrays
CurrentArray = objFPCArrays.CurrentArray.Name

Applies To

FPCArrays


FPCArrays.Item Method

Returns an FPCArray object from the collection. The object is specified by the required integer parameter.

Syntax

[ vItem = ] FPCArrays.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCArray. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCArrays


FPCArrays.Refresh Method

Restores all original values to the FPCArrays collection. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

Syntax

FPCArrays.Refresh()

Applies To

FPCArrays


FPCArrays.Remove Method

Removes the specified array from the collection.

Syntax

FPCArrays.Remove( vIndex )

Parameters

vIndex
Required. Name or one-based index of the FPCArray object to remove.

Applies To

FPCArrays


FPCArrays.Save Method

Saves all configuration changes to persistent storage. Note that any changes made will not be saved unless the Save method is called.

Syntax

FPCArrays.Save()

Example

In the following example, the changes will not be saved until the Save method is called in the last line of code.

Dim objFPC As New FPCLib.FPC
Dim FPCArraysName As String
Dim objFPCArrays As FPCArrays
Set objFPCArrays = objFPC.Arrays
objFPCArrays.CurrentArray.Name = "CurrentArray"
objFPCArrays.Save

Applies To

FPCArrays


FPCArrayPolicy Object

The FPCArrayPolicy object stores the topology of the ISA configuration. You can use this object to retrieve all IP packet filters, protocols rules, site and content rules, routing rules, and publishing rules valid for the current server array.

The FPCArrayPolicy object is a property of the FPCArray object.

Note to C++ Programmers

This object implements the IFPCArrayPolicy interface.

Methods

The following table lists the methods of the FPCArrayPolicy object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.
Save | Saves the object's configuration information to persistent storage.

Properties

The following table lists the properties of the FPCArrayPolicy object.

Property | Description
IpPacketFilters | Retrieves a collection of IP packet filters in this array.
ProtocolRules | Retrieves a collection of the protocol rules.
SiteAndContentRules | Retrieves a collection of all site and content rules in this array.
WebProxy | Retrieves the FPCWebProxy object.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCArrayPolicy.IpPacketFilters Property

Retrieves a collection of IP packet filters on this server.

Syntax

[ collFPCIpPacketFilters = ] FPCArrayPolicy.IpPacketFilters

Possible Values

collFPCIpPacketFilters
Reference to an FPCIpPacketFilters collection.

The property is read-only.

Applies To

FPCArrayPolicy


FPCArrayPolicy.ProtocolRules Property

Retrieves a collection of the protocol rules.

Syntax

[ collFPCProtocolRules = ] FPCArrayPolicy.ProtocolRules

Possible Values

collFPCProtocolRules
Reference to the FPCProtocolRules collection.

Applies To

FPCArrayPolicy

See Also

FPCProtocolRule


FPCArrayPolicy.Refresh Method

Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.

Syntax

FPCArrayPolicy.Refresh()

Applies To

FPCArrayPolicy


FPCArrayPolicy.Save Method

Saves the object's configuration information to persistent storage.

Syntax

FPCArrayPolicy.Save()

Applies To

FPCArrayPolicy


FPCArrayPolicy.SiteAndContentRules Property

Retrieves a collection of all site and content rules in this array.

Syntax

[ collFPCSiteAndContentRules = ] FPCArrayPolicy.SiteAndContentRules

Possible Values

collFPCSiteAndContentRules
Reference to an FPCSiteAndContentRules collection.

Applies To

FPCArrayPolicy

See Also

FPCSiteAndContentRule


FPCArrayPolicy.WebProxy Property

Retrieves the FPCWebProxy object.

Syntax

[ oFPCWebProxy = ] FPCArrayPolicy.WebProxy

Possible Values

oFPCWebProxy
Reference to the FPCWebProxy object.

The property is read-only.

Applies To

FPCArrayPolicy


FPCArrayPolicyConfig Object

The FPCArrayPolicyConfig object is used to associate a global policy with an array. This object is a member of the FPCArrayPolicyConfigs collection.

Note to C++ Programmers

This object implements the IFPCArrayPolicyConfig interface.

Methods

The following table lists the methods of the FPCArrayPolicyConfig object.

Method | Description
Refresh | Reads the object from persistent storage, discarding any changes to the object that were not saved.
Save | Saves the object's configuration to persistent storage.
SetPolicy | Sets the values of the PolicyUsedFlag and PolicyName properties.

Properties

The following table lists the properties of the FPCArrayPolicyConfig object.

Property | Description
AllowPublishing | Sets or returns a Boolean value that allows definition of publishing rules in an array.
ArrayName | Sets or returns the array name of this configuration object.
ForcePacketFiltering | Sets or returns a Boolean value that forces IP packet filtering in an array.
PolicyName | Returns the global-policy object associated with the given array.
PolicyUsedFlag | Returns a value that specifies whether the array can uses local and/or enterprise policy.
UseDefaults | Sets or returns the UseDefaults value to which this object applies. When UseDefaults is set to TRUE, the array will use the default policy configuration set in the FPCEnterprise object.
VendorParametersSets | Returns a reference to an object that stores vendor-specific data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCArrayPolicyConfig.AllowPublishing Property

Sets or returns a Boolean value that allows definition of publishing rules in an array.

Syntax

FPCArrayPolicyConfig.AllowPublishing [ = bAllowPublishing ]

Possible Values

bAllowPublishing
A Boolean value that determines whether definition of publishing rules is allowed in an array.

This property is read-write.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.ArrayName Property

Sets or returns the array name to which this object applies.

Syntax

FPCArrayPolicyConfig.ArrayName [ = sName ]

Possible Values

sName
String that specifies the parameter name for which to retrieve the value.

The property is read-only.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.ForcePacketFiltering Property

Sets or returns a Boolean value that forces IP packet filtering in an array.

Syntax

[ bForce = ] FPCArrayPolicyConfig.ForcePacketFiltering

Possible Values

bForce
Boolean value that determines whether IP packet filtering is forced in an array.

The property is read-write.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.PolicyName Property

Returns the name of the policy that is associated with the array.

Syntax

[ sName = ] FPCArrayPolicyConfig.PolicyName

Possible Values

sName
String that specifies the policy name.

The property is read only.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.PolicyUsedFlag Property

Returns a value that specifies whether the array uses its local and/or enterprise policy.

Syntax

[ PolicyUsed = ] FPCArrayPolicyConfig.PolicyUsedFlag

Possible Values

PolicyUsed
The policy that is used. It can have a value from the FpcPolicyUsed enumerated type.

The property is read only, but can be set in SetPolicy.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.Refresh Method

Reads the object from persistent storage, discarding any changes to the object that were not saved.

Syntax

FPCArrayPolicyConfig.Refresh()

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.Save Method

Saves the object's configuration to persistent storage.

Syntax

FPCArrayPolicyConfig.Save()

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.SetPolicy Method

Sets the values of the PolicyUsedFlag and PolicyName properties.

Syntax

FPCArrayPolicyConfig.SetPolicyP( Flag, sPolicy )

Parameters

Flag
A value that specifies whether an array uses local and/or enterprise policy.
sPolicy
A string that specifies the name of the policy. It can be empty to indicate that the array is not using an enterprise policy.

Note

You need to set FPCArrayPolicyConfig.UseDefaults = False before you update the policy.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.UseDefaults Property

Sets or returns the UseDefaults value to which the FPCArrayPolicyConfig object applies. When UseDefaults is set to TRUE, the array will use the default policy configuration set in the FPCEnterprise object.

Syntax

FPCArrayPolicyConfig.UseDefaults [ = bUseDefaults ]

Parameters

bUseDefaults
A Boolean value that specifies whether to use the default settings of the object.
The property is read-write.

Applies To

FPCArrayPolicyConfig

Note

You cannot define a local policy configuration when bUseDefaults equals TRUE.


FPCArrayPolicyConfig.VendorParametersSets Property

Returns a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection will be backed up with all other ISA objects.

Syntax

[ collFPCVendorParametersSets = ] FPCArrayPolicyConfig.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfigs Collection

The FPCArrayPolicyConfigs collection provides access to a group of FPCArrayPolicyConfig objects. This collection therefore contains the policy collections of all ISA arrays

FPCArrayPolicyConfigs is a property of the FPCEnterprise object.

Note to C++ Programmers

This collection implements the IFPCArrayPolicyConfigs interface.

Methods

The following table lists the methods of the FPCArrayPolicyConfigs collection.

Method | Description
Item | Returns the FPCArrayPolicyConfig object specified by the integer parameter of this method.
Refresh | Refreshes all the properties of the object, returning them to the values they held when the object was first created.
Save | Saves all configuration changes to persistent storage.

Properties

The following table lists the properties of the FPCArrayPolicyConfigs collection.

Property | Description
Count | Returns the number of policy objects in the collection.
VendorParametersSets | Used to programmatically access vendor-specific data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCArrayPolicyConfigs.Count Property

Returns the number of FPCArrayPolicyConfig objects within the collection.

Syntax

[ lCount = ] FPCArrayPolicyConfigs.Count

Possible Values

lCount
Long value that specifies the number of FPCArrayPolicyConfig objects.

The property is read-only.

Applies To

FPCArrayPolicyConfigs


FPCArrayPolicyConfigs.Item Method

Returns an FPCArrayPolicyConfig object from the collection. The object is specified by the required integer parameter.

Syntax

[ vItem = ] FPCArrayPolicyConfigs.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCArrayPolicyConfig. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCArrayPolicyConfigs


FPCArrayPolicyConfigs.Refresh Method

Restores all original values to the FPCArrayPolicyConfigs collection. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

Syntax

FPCArrayPolicyConfigs.Refresh()

Applies To

FPCArrayPolicyConfigs


FPCArrayPolicyConfigs.Save Method

Saves all configuration changes to persistent storage.

Syntax

FPCArrayPolicyConfigs.Save()

Applies To

FPCArrayPolicyConfigs


FPCArrayPolicyConfigs.VendorParametersSets Property

Returns a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection will be backed up from the Active Directory with all other FPC objects.

Syntax

[ collFPCVendorParametersSets = ] FPCArrayPolicyConfigs.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCArrayPolicyConfigs


FPCAutoDial Object

The FPCAutoDial object represents an automatic-dial state (enabled or disabled) and phone-book entry. A network can be configured so that it automatically dials out of the network for specific requests. The dialup entry provides information on how to dial.

This object is a property of the FPCRoutingRule, FPCPrimaryRoute, FPCBackupRoute, and FPCFirewallChaining objects.

Note to C++ Programmers

This collection implements the IFPCAutoDial interface.

Methods

The following table lists the methods of the FPCAutoDial object.

Method | Description
Refresh | Restores all original values to the FPCAutoDial object.
Save | Saves current configuration to persistent storage.
SetAutoDial | Set the EnableAutoDial and DialupEntry properties.

Properties

The following table lists the properties of the FPCAutoDial object.

Property | Description
EnableAutoDial | Retrieves if the auto dial function is enabled.
DialupEntry | Retrieves the FPCRef object that specifies the dialup entry.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCAutoDial object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAutoDial.DialupEntry Property

Retrieves the FPCRef object that specifies the dialup entry.

Syntax

[ oFPCRef = ] FPCAutoDial.DialupEntry

Possible Values

oFPCRef
Returns a reference to an FPCRef object.

The property is read-only.

Applies To

FPCAutoDial


FPCAutoDial.EnableAutoDial Property

Retrieves if the auto dial is enabled.

Syntax

[ bEnabled = ] FPCAutoDial.EnableAutoDial

Possible Values

bEnabled
A Boolean value that has either of these settings:
Setting | Meaning
TRUE | FPCAutoDial is enabled.
FALSE | FPCAutoDial is disabled.

The property is read-only.

Applies To

FPCAutoDial


FPCAutoDial.Refresh Method

Reads the object configuration from persistent storage, discarding any changes to it that were not saved.

Syntax

FPCAutoDial.Refresh()

Applies To

FPCAutoDial


FPCAutoDial.Save Method

Saves the state of the rule to persistent storage.

Syntax

FPCAutoDial.Save()

Applies To

FPCAutoDial


FPCAutoDial.SetAutoDial Method

Sets the EnableAutoDial and DialupEntry properties.

Syntax

FPCAutoDial.SetAutoDial(bEnable, sEntryName)

Parameters

bEnable
Required. Boolean value that specifies whether the EnableAutoDial property is enabled or disabled.
sEntryName

Optional. String that defines the name of the dialup entry.

Only used if bEnable equals TRUE.

Applies To

FPCAutoDial


FPCAutoDial.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCAutoDial object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCAutoDial.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCAutoDial


FPCBackupRoute Object

The FPCBackupRoute object represents the backup route entity, either a single ISA server or a domain array of ISA servers. This object is a property of the FPCPrimaryRoute object, which you can access through the FPCPrimaryRoute.BackupRoute property.

Note to C++ Programmers

This object implements the IFPCBackupRoute interface.

Methods

The following table lists the methods of the FPCBackupRoute object.

Method | Description
Refresh | Reads the object's information from persistent storage.
Save | Saves the object's configuration to persistent storage.
SetAutoPollConfig | Sets whether proxy polling of the upstream proxy server or domain array for membership information is enabled.
SetServerAndPort | Sets the server and port for the entity.

Properties

The following table lists the properties of the FPCBackupRoute object.

Property | Description
AuthenticationEnabled | Sets or retrieves whether the use of authentication in upstream routing is enabled.
AuthenticationType | Sets or retrieves the type of authentication that the entity uses.
AutoDialOut | Retrieves a reference to an FPCAutoDial object that represents the automatic-dial settings.
AutomaticPollConfig | Retrieves whether proxy polling of the upstream proxy or domain array for membership information is enabled.
BackupRouteType | Sets or retrieves the backup route type.
Credentials | Retrieves an FPCCredentials object used to read and write credentials information. This information will be used if a proxy server needs to authenticate with an upstream proxy server.
PollAtUrl | Sets or retrieves the URL, usually at the upstream proxy, at which to poll for the domain array configuration information. This property if valid if the AutomaticPollConfig property is enabled.
PollAtUrlCpid | Retrieves the code page ID (Cpid) of a URL.
RouteServerName | Retrieves the name of the proxy or domain array.
RouteServerPort | Retrieves the port that this entity is listening on.
RouteServerSSLPort | Sets or retrieves the port for listening on a secure channel.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCBackupRoute.AuthenticationEnabled Property

Sets or retrieves whether the use of authentication in upstream routing is enabled.

Syntax

FPCBackupRoute.AuthenticationEnabled [= bEnabled ]

Possible Values

bEnabled
Boolean value that has either of two settings:
Setting | Meaning
TRUE | Authentication is enabled.
FALSE | Authentication is disabled.

The property is read-write.

Applies To

FPCBackupRoute


FPCBackupRoute.AuthenticationType Property

Sets or retrieves the type of authentication that the entity uses.

Syntax

FPCBackupRoute.AuthenticationType [ = AuthType ]

Possible Values

AuthType
Authentication type. It can have a value from the FpcAuthType enumeration.

The property is read-write.

Remarks

Basic authentication (fpcUiAuthBasic) is not encrypted.

Applies To

FPCBackupRoute


FPCBackupRoute.AutoDialOut Property

Retrieves a reference to an FPCAutoDial object that represents the automatic-dial settings.

Syntax

[ oFPCAutoDial = ] FPCBackupRoute.AutoDialOut

Possible Values

oFPCAutoDial
Refrence to an FPCAutoDial object that represents the auto dial settings.

The property is read-only.

Applies To

FPCBackupRoute


FPCBackupRoute.AutomaticPollConfig Property

Retrieves whether proxy polling of the upstream proxy or domain array is enabled for membership information.

Syntax

FPCBackupRoute.AutomaticPollConfig [ = bEnabled ]

Possible Values

bEnabled
A Boolean value that has either of these settings:.
Setting | Meaning
TRUE | Proxy polling is enabled.
FALSE | Proxy polling is disabled.

The property is read-only. It can be modified through the SetAutoPollConfig method.

Applies To

FPCBackupRoute


FPCBackupRoute.BackupRouteType Property

Sets or retrieves the backup route type.

Syntax

[ RouteType = ]
FPCBackupRoute.BackupRouteType

Possible Values

RouteType
Route Type. It can have a value from the FpcBackupRouteType enumerated type.

The property is read-write.

Applies To

FPCBackupRoute


FPCBackupRoute.Credentials Property

Retrieves an FPCCredentials object to read and write credential information. A proxy server will use this information if it needs to authenticate a connection to an upstream proxy server.

Syntax

[ oFPCCredentials = ] FPCBackupRoute.Credentials

Possible Values

oFPCCredentials
Reference to an FPCCredentials object.

The property is read-only.

Applies To

FPCBackupRoute


FPCBackupRoute.PollAtUrL Property

Sets or retrieves the URL, usually at the upstream proxy, to poll for the domain-array configuration information. This property is valid if the AutomaticPollConfig property is enabled.

Syntax

FPCBackupRoute.PollAtURL [ = sURL ]

Possible Values

sURL
String that specifies the URL.

The property is read-only.

Applies To

FPCBackupRoute


FPCBackupRoute.PollAtUrlCpid Property

Retrieves the code page identifier (Cpid) of a URL. The Cpid is useful if a URL string contains national characters that are not ANSI standard; for example, if a URL string contains Japanese characters.

Syntax

[ lCpid = ] FPCBackupRoute.PollAtUrlCpid

Return Value

lCpid
Long that specifies the Cpid of a URL.

The property is read-only.

Applies To

FPCBackupRoute


FPCBackupRoute.Refresh Method

Reads the object's information from persistent storage.

Syntax

FPCBackupRoute.Refresh()

Applies To

FPCBackupRoute


FPCBackupRoute.RouteServerName Property

Retrieves the name of the proxy or domain array.

Syntax

[ sName = ] FPCBackupRoute.RouteServerName

Possible Values

sName
String that specifies the name of the proxy or domain array.

The property is read-only.

Applies To

FPCBackupRoute


FPCBackupRoute.RouteServerPort Property

Retrieves the port on which the entity is listening.

Syntax

[ lPort = ] FPCBackupRoute.RouteServerPort

Possible Values

lPort
Long value that specifies the port number. It can be a value from 1 to 65535.

The property is read-only.

Applies To

FPCBackupRoute


FPCBackupRoute.RouteServerSSLPort Property

Sets or retrieves the port for listening on a secure channel.

Syntax

[ lSSLPort = ] FPCBackupRoute.RouteServerSSLPort

Possible Values

lSSLPort
Long value that specifies the port number. It can be a value from 1 to 65535.

The property is read-write.

Applies To

FPCBackupRoute


FPCBackupRoute.Save Method

Saves the object's configuration to persistent storage.

Syntax

FPCBackupRoute.Save()

Applies To

FPCBackupRoute


FPCBackupRoute.SetAutoPollConfig Method

Sets whether proxy polling of the upstream proxy or domain array is enabled for membership information.

Syntax

FPCBackupRoute.SetAutoPollConfig(fSetAuto, sAutoPollUrl, lCpidUrl)

Parameters

fSetAuto
Boolean expression that specifies whether automatic configuration is to be enabled.
sAutoPollUrl
Optional. String that specifies the URL, usually at the upstream proxy, to poll for the domain-array configuration information. If fSetAuto is set to TRUE, this parameter must hold a valid URL; otherwise, sAutoPollUrl is ignored.
lCpidUrl
Optional. Long value that specifies the code page for the URL.

This property is read-write.

Applies To

FPCBackupRoute


FPCBackupRoute.SetServerAndPort Method

Sets the server and port for the entity.

Syntax

FPCBackupRoute.SetServerAndPort( sServerName, lPort )

Parameters

sServerName
String that specifies the name of the server.
lPort
Long value that specifies the port number that the server listens on. It can be a value from 1 to 65535.

Applies To

FPCBackupRoute


FPCBandwidthPriority Object

The FPCBandwidthPriority object represents a single bandwidth priority entry. You can modify internal or external bandwidth with this object. Bandwidth priorities are used by the rules to define bandwidth resource allocation among competing requests.

ISA administrators control the amount of bandwidth that is allocated for any specific Internet request. You can configure External bandwidth priority, the bandwidth priority allocated for communication with the Internet, and Internal bandwidth priority, the bandwidth priority allocated for communication among computers behind the ISA server.

This object is a member of the FPCBandwidthPriorities collection.

Note to C++ Programmers

This object implements the IFPCBandwidthPriority interface.

Methods

The following table lists the methods of the FPCBandwidthPriority object.

Method | Description
Refresh | Reads the object's data from persistent storage, discarding any changes to the data that were not saved.
Save | Saves all the object's data to persistent storage.

Properties

The following table lists the properties of the FPCBandwidthPriority object.

Property | Description
BandwidthExternalWeight | Sets or retrieves the bandwidth for external traffic defined by the FPCBandwidthPriority object.
BandwidthInternalWeight | Sets or retrieves bandwidth for internal traffic defined by the FPCBandwidthPriority object.
Description | Sets or retrieves the description of the FPCBandwidthPriority object.
Name | Sets or retrieves the name of the FPCBandwidthPriority object.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCBandwidthPriority.BandwidthExternalWeight Property

Sets or retrieves the bandwidth for external traffic defined by the bandwidth priority.

Syntax

FPCBandwidthPriority.BandwidtExternalWeight [ = lBandwidthExternalWeight ]

Possible Values

lBandwidthExternalWeight
Long that specifies the weight of the bandwidth priority (0-200).

The property is read-write.

Applies To

FPCBandwidthPriority


FPCBandwidthPriority.BandwidthInternalWeight Property

Sets or retrieves bandwidth for internal traffic defined by the bandwidth priority.

Syntax

FPCBandwidthPriority.BandwidtInternalWeight [ = lBandwidthInternalWeight ]

Possible Values

lBandwidthInternalWeight
Long that specifies the internal bandwidth of the bandwidth priority (0-200).

The property is read-write.

Applies To

FPCBandwidthPriority


FPCBandwidthPriority.Description Property

Sets or retrieves the description of the bandwidth priority.

Syntax

FPCBandwidthPriority.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the bandwidth priority.

The property is read-write.

Applies To

FPCBandwidthPriority


FPCBandwidthPriority.Name Property

Sets or retrieves the name of the bandwidth priority.

Syntax

FPCBandwidthPriority.Name [ = sName ]

Possible Values

sName
String that specifies the name of the bandwidth priority.

The property is read-write.

Applies To

FPCBandwidthPriority


FPCBandwidthPriority.Refresh Method

Reads the object's data from persistent storage, discarding any changes to the data that were not saved.

Syntax

FPCBandwidthPriority.Refresh()

Applies To

FPCBandwidthPriority


FPCBandwidthPriority.Save Method

Saves all the object's data to persistent storage.

Syntax

FPCBandwidthPriority.Save()

Applies To

FPCBandwidthPriority


FPCBandwidthPriority.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCBandwidthPriority object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCBandwidthPriority.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCBandwidthPriority


FPCBandwidthPriorities Collection

The FPCBandwidthPriorities collection represents a group of FPCBandwidthPriority objects. Bandwidth priorities are used by the rules to define bandwidth resource allocation among competing requests.

The FPCBandwidthPriorities collection is a property of the FPCPolicyElements object.

Note to C++ Programmers

This collection implements the IFPCBandwidthPriorities interface.

Methods

The following table lists the methods of the FPCBandwidthPriorities collection.

Method | Description
Add | Creates a new FPCBandwidthPriority object in the collection and returns a reference to it.
Item | Retrieves the given FPCBandwidthPriority object from the collection.
Refresh | Reads all objects in the collection from persistent storage, discarding any changes to current FPCBandwidthPriorities entries that were not saved.
Remove | Removes an FPCBandwidthPriority object from the collection.
Save | Saves all the objects in the collection to persistent storage.

Properties

The following table lists the properties of the FPCBandwidthPriorities collection.

Property | Description
Count | Retrieves the number of FPCBandwidthPriority objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCBandwidthPriorities collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCBandwidthPriorities.Add Method

Creates a new FPCBandwidthPriority object in the collection and returns a reference to it.

Syntax

[ oFPCBandwidthPriority = ] FPCBandwidthPriorities.Add( sName, lBandwidthInternalWeight, lBandwidthExternalWeight )

Parameters

sName
Required. String that specifies the name of the new FPCBandwidthPriority entry.
lBandwidthInternalWeight
Required. Long that specifies the bandwidth for internal traffic that will be defined by the new FPCBandwidthPriority entry.
lBandwidthExternalWeight
Required. Long that specifies the bandwidth for external traffic defined by the new FPCBandwidthPriority entry.

Return Values

oFPCBandwidthPriority
Reference to an FPCBandwidthPriority object.

Applies To

FPCBandwidthPriorities


FPCBandwidthPriorities.Count Property

Retrieves the number of FPCBandwidthPriority objects in the collection.

Syntax

[ lCount = ] FPCBandwidthPriorities.Count

Possible Values

lCount
Long value that specifies the number of FPCBandwidthPriority objects.

The property is read-only.

Applies To

FPCBandwidthPriorities


FPCBandwidthPriorities.Item Method

Retrieves the given FPCBandwidthPriority object from the collection.

Syntax

[ vItem = ] FPCBandwidthPriorities.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCBandwidthPriority. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCBandwidthPriorities


FPCBandwidthPriorities.Refresh Method

Reads all objects from persistent storage, discarding any changes that were not saved.

Syntax

FPCBandwidthPriorities.Refresh()

Applies To

FPCBandwidthPriorities


FPCBandwidthPriorities.Remove Method

Removes an FPCBandwidthPriority object from the collection.

Syntax

FPCBandwidthPriorities.Remove( vItem )

Parameters

vItem
Required. One-based index of the object to remove.

Applies To

FPCBandwidthPriorities


FPCBandwidthPriorities.Save Method

Saves all items in the collection to persistent storage.

Syntax

FPCBandwidthPriorities.Save()

Applies To

FPCBandwidthPriorities


FPCBandwidthPriorities.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCBandwidthPriority object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCBandwidthPriorities.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCBandwidthPriorities


FPCBandwidthRule Object

The FPCBandwidthRule object represents a single bandwidth rule. A bandwidth rule defines the bandwidth to be allocated for various types of requests. You define a bandwidth rule by using ISA's policy elements and by establishing the requests to which the rule will apply. This object is a member of the FPCBandwidthRules collection.

Note to C++ Programmers

This collection implements the IFPCBandwidthRule interface.

Methods

The following table lists the methods of the FPCBandwidthRule object.

Method | Description
Refresh | Reads the collection from persistent storage, discarding any changes to it that were not saved.
Save | Saves the state of the rule to persistent storage.
SetAppliesAlways | Sets the rule to apply always, regardless of the ScheduleTemplateUsed property.
SetDestination | Sets the destinations to which the rule applies.
SetSchedule | Sets the value of the schedule that applies to this rule.

Properties

The following table lists the properties of the FPCBandwidthRule object.

Property | Description
AppliesAlways | Retrieves whether the rule applies at all times.
AppliesToAccounts | Retrieves the collection of accounts to which the rule applies.
AppliesToContentMethodType | Sets or retrieves the selection of content to which the rule applies.
AppliesToDestination | Sets or retrieves the type of destination to which the rule applies.
AppliesToMethod | Sets or retrieves the method used for deciding rule applicability.
BandwidthPriorityUsed | Retrieves the name of the FPCBandwidthPriority object that is used to define the bandwidth applicable to this rule.
ClientAddressSetsExcluded | Retrieves the collection of client sets to which the rule does not apply.
ClientAddressSetsUsed | Retrieves the collection of client sets to which the rule applies.
ContentGroupsUsed | Represents a collection of the content groups to which the rule applies.
Description | Sets or retrieves the description of the set.
DestinationSetUsed | Retrieves the FPCRefs collection used to define the destination to which the rule applies.
Enabled | Sets or retrieves whether the rule is enabled.
IsDefault | Retrieves whether the rule is pre-installed and cannot be deleted.
Name | Sets or retrieves the name of the bandwidth rule.
Order | Retrieves the filter's order.
ProtocolSelectionMethod | Sets or retrieves whether the rule applies to all IP traffic, all protocols, or specified protocols.
ScheduleUsed | Sets or retrieves the name of the schedule template object used to define the times when the rule applies.
SetBandwidthPriority | Sets the bandwidth rule to use windows quality of service (QOS) or a specific bandwidth priority.
SpecifiedProtocols | Retrieves the FPCRefs collection used by the rule.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the object's storage.
WindowsQoSEnabled | Retrieves whether the rule uses the defualt windows QOS bandwidth.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCBandwidthRule.AppliesAlways Property

Retrieves whether the rule applies at all times.

Syntax

[ bApplies = ] FPCBandwidthRule.AppliesAlways

Possible Values

bApplies
A Boolean value that has either of these settings:
Setting | Meaning
TRUE | Rule always applies.
FALSE | Rule does not always apply.

The property is read only. It can be set to TRUE by calling the SetAppliesAlways method. Choosing a schedule by calling ScheduleUsed will set the property to FALSE.

Applies To

FPCBandwidthRule


FPCBandwidthRule.AppliesToAccounts Property

Retrieves the collection of accounts to which the rule applies.

Syntax

[ collFPCAccounts = ] FPCBandwidthRule.AppliesToAccounts

Possible Values

collFPCAccounts
Reference to the FPCAccounts collection.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.AppliesToContentMethodType Property

Sets or retrieves the selection of content to which the rule applies.

Syntax

FPCBandwidthRule.AppliesToContentMethodType [ = Applies ]

Possible Values

Applies
Applies to content. It can have a value from the FpcAppliesToContentMethod enumerated type.

The property is read-write.

Applies To

FPCBandwidthRule


FPCBandwidthRule.AppliesToDestination Property

Sets or retrieves the type of destination to which the rule applies.

Syntax

FPCBandwidthRule.AppliesToDestination [ = DestinationSelection ]

Possible Values

DestinationSelection
Type of destination to which the rule applies. It can have a value from the FpcDestinationSelection enumerated type.

The property is read-only. It can be set using the SetDestination method.

Applies To

FPCBandwidthRule


FPCBandwidthRule.AppliesToMethod Property

Sets or retrieves the method used for deciding rule applicability.

Syntax

FPCBandwidthRule.AppliesToMethod [ = AppliesToType]

Possible Values

AppliesToType
Applicability method. It can have a value from the FpcAppliesToType enumeration type.

The property is read-write.

Applies To

FPCBandwidthRule


FPCBandwidthRule.BandwidthPriorityUsed Property

Retrieves the name of the bandwidth priority object used to define the bandwidth that applies to this rule.

Syntax

FPCBandwidthRule.BandwidthPriorityUsed [ = sTemplate ]

Possible Values

sTemplate
String that specifies the name of the bandwidth priority object.

The property is read-write.

Applies To

FPCBandwidthRule


FPCBandwidthRule.ClientAddressSetsExcluded Property

Retrieves the collection of client address sets to which the rule does not apply.

Syntax

[ collFPCRefs = ] FPCBandwidthRule.ClientAddressSetsExcluded

Return Values

collFPCRefs
Reference to the FPCRefs collection that contains references to the client address sets that are excluded.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.ClientAddressSetsUsed Property

Retrieves the collection of client address sets to which the rule applies.

Syntax

[ collFPCRefs = ] FPCBandwidthRule.ClientAddressSetsUsed

Return Values

collFPCRefs
Reference to the FPCRefs collection that contains references to the client address sets that are used.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.ContentGroupsUsed Property

Retrieves the collection of content groups to which the rule applies.

Syntax

[ collContentGroupsUsed = ] FPCBandwidthRule.ContentGroupsUsed

Return Values

collContentGroupsUsed
Reference to the FPCRefs collection.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.Description Property

Sets or retrieves the description of the set.

Syntax

FPCBandwidthRule.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the bandwidth rule.

The property is read-write.

Applies To

FPCBandwidthRule


FPCBandwidthRule.DestinationSetUsed Property

Retrieves the FPCRef object used to define the destination to which the rule applies.

Syntax

[ oFPCRef = ] FPCBandwidthRule.DestinationSetUsed

Possible Values

oFPCRef
The FPCRef object that is used to define the destination to which the rule applies.

The property is read-only. It can be set using the SetDestination method.

Applies To

FPCBandwidthRule


FPCBandwidthRule.Enabled Property

Sets or retrieves whether the rule is enabled.

Syntax

FPCBandwidthRule.Enabled [ = bEnabled ]

Possible Values

bEnabled
A Boolean value that has either of these settings:
Setting | Meaning
TRUE | Rule is enabled.
FALSE | Rule is disabled.

The property is read-write.

Applies To

FPCBandwidthRule


FPCBandwidthRule.IsDefault Property

Retrieves whether the rule is a pre-installed rule, which cannot be deleted. You cannot change the properties of the default rule.

Syntax

[ bPreInstalled = ] FPCBandwidthRule.IsDefault

Possible Values

bPreInstalled
A Boolean value that has either of these settings:
Setting | Meaning
TRUE | Rule is pre-installed.
FALSE | Rule is not pre-installed.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.Name Property

Sets or retrieves the name of the bandwidth rule.

Syntax

FPCBandwidthRule.Name [ = sName ]

Possible Values

sName
String that specifies the name of the bandwidth rule.

The property is read-write.

Applies To

FPCBandwidthRule


FPCBandwidthRule.Order Property

Retrieves the filter's order.

Syntax

[ lOrder = ] FPCISAPIFilter.Order

Possible Values

lOrder
Long value that specifies the order of the filter.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.ProtocolSelectionMethod Property

Sets or retrieves whether the rule applies to all Internet Protocol (IP) traffic or to specified protocols.

Syntax

FPCBandwidthRule.ProtocolSelectionMethod [ = ProtocolSelectionType ]

Possible Values

ProtocolSelectionType
Protocol selection type. It can have a value from the FpcProtocolSelectionType enumerated type.

The property is read-write.

Applies To

FPCBandwidthRule


FPCBandwidthRule.Refresh Method

Reads the cache configuration from persistent storage, discarding any changes to it that were not saved.

Syntax

FPCBandwidthRule.Refresh()

Applies To

FPCBandwidthRule


FPCBandwidthRule.Save Method

Saves the state of the rule to persistent storage.

Syntax

FPCBandwidthRule.Save()

Applies To

FPCBandwidthRule


FPCBandwidthRule.ScheduleUsed Property

Retrieves the FPCRef object that is used to define the times when the rule applies.

Syntax

[ oFPCRef = ] FPCBandwidthRule.ScheduleUsed

Possible Values

oFPCRef
The FPCRef object that is used to define the times when the rule applies.

The property is read only. The value of this property can be set using the SetSchedule method.

Applies To

FPCBandwidthRule


FPCBandwidthRule.SetAppliesAlways Method

Sets the rule to apply always, regardless of the value of the ScheduleUsed property.

Syntax

FPCBandwidthRule.SetAppliesAlways()

Applies To

FPCBandwidthRule


FPCBandwidthRule.SetBandwidthPriority Property

Sets the bandwidth rule to use Windows quality of service (QOS) or a specific bandwidth priority.

Syntax

FPCBandwidthRule.SetBandwidthPriority( bIsWindowsQoS, sNewClass )

Parameters

bIsWindowsQoS
A Boolean value that has either of these settings:
Setting | Meaning
TRUE | Rule uses Windows QOS bandwidth.
FALSE | Rule uses the specified bandwidth priority.

sBandwidthClass
Optional. String that defines a bandwidth priority to use. Only used if bIsWindowsQoS equals FALSE.

The property is read only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.SetDestination Method

Sets the destinations to which the rule applies.

Syntax

FPCBandwidthRule.SetDestination( DestType, sDestinationSet, ItemScope )

Parameters

DestType
Required. Defines the type of destinations to which the rule applies. Can have a value from the FpcDestinationSelection enumerated type.
sDestinationSet
Optional. String that defines a set of destinations to use. Only used if DestType equals the value FPCDestinationSet.
ItemScope
The item scope. Can have a value from the FpcItemScope enumeration.

Applies To

FPCBandwidthRule


FPCBandwidthRule.SetSchedule Method

Sets the value of the schedule that applies to this rule.

Syntax

FPCBandwidthRule.SetSchedule( sScheduleName, Scope )

Parameters

sScheduleName
String that specifies the name of the ScheduleTemplate object used by this rule.
Scope
Item scope. It can have a value from the FpcItemScope enumeration.

Applies To

FPCBandwidthRule


FPCBandwidthRule.SpecifiedProtocols Property

Retrieves the FPCRefs collection used by the rule.

Syntax

[ collFPCRefs = ] FPCBandwidthRule.SpecifiedProtocols

Possible Values

collFPCRefs
Reference to the FPCRefs collection.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCBandwidthRule object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCBandwidthRule.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.WindowsQoSEnabled Property

Retrieves whether the rule uses the default Windows quality-of-service (QOS) bandwidth.

Syntax

FPCBandwidthRule.WindowsQoSEnabled [ = bApplies ]

Possible Values

bApplies
A Boolean value that has either of these settings:
Setting | Meaning
TRUE | Rule uses Windows QOS bandwidth.
FALSE | Rule does not use Windows QOS bandwidth.

The property is read only.

Applies To

FPCBandwidthRule


FPCBandwidthRules Collection

The FPCBandwidthRules collection provides access to a group of FPCBandwidthRule objects. This collection is a property of the FPCArrayPolicy object.

Note to C++ Programmers

This collection implements the IFPCBandwidthRules interface.

Methods

The following table lists the methods of the FPCBandwidthRules collection.

Method | Description
Add | Creates a new rule, adds it to the collection, and returns a reference to it.
Item | Retrieves the given FPCBandwidthRule object from the collection.
MoveDown | Moves the given rule one step down in the order of execution.
MoveUp | Moves the given rule one step up in the order of execution.
Refresh | Reads all the rule objects from persistent storage, discarding any changes to the current rule objects that were not saved.
Remove | Removes a rule object from the collection.
Save | Saves all modified rules to persistent storage.

Properties

The following table lists the properties of the FPCBandwidthRules collection.

Property | Description
Count | Retrieves the number of rule objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCBandwidthRules.Add Method

Creates a new rule, adds it to the collection, and returns a reference to it.

Syntax

[ oFPCBandwidthRule = ] FPCBandwidthRules.Add( sRuleName )

Parameters

sRuleName
Required. String that specifies the name of the rule. A string of zero length (not NULL) specifies intrinsic protocols.

Return Valuess

oFPCBandwidthRule
Reference to the new FPCBandwidthRule object.

Applies To

FPCBandwidthRules


FPCBandwidthRules.Count Property

Retrieves the number of rule objects in the collection.

Syntax

[ lCount = ] FPCBandwidthRules.Count

Possible Values

lCount
Long value that specifies the number of rule objects.

The property is read-only.

Applies To

FPCBandwidthRules

See Also

FPCBandwidthRule


FPCBandwidthRules.Item Method

Retrieves the given FPCBandwidthRule object from the collection.

Syntax

[ vItem = ] FPCBandwidthRules.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
Variant. Returns an object if successful; NULL otherwise.

Applies To

FPCBandwidthRules


FPCBandwidthRules.MoveDown Method

Moves the given rule one step down in the order of execution.

Syntax

FPCBandwidthRules.MoveDown( lIndex )

Parameters

lIndex
Required. Long containing the index (current location in the order) of the rule to move down in the order of execution.

Applies To

FPCBandwidthRules

See Also

MoveUp


FPCBandwidthRules.MoveUp Method

Moves the given rule one step up in the order of execution.

Syntax

FPCBandwidthRules.MoveUp( lIndex )

Parameters

lIndex
Required. Long value that contains the index (current location in the order) of the rule to move up in the order of execution.

Applies To

FPCBandwidthRules

See Also

MoveDown


FPCBandwidthRules.Refresh Method

Reads all the rule objects from persistent storage, discarding any changes to the current rule objects that were not saved.

Syntax

FPCBandwidthRules.Refresh()

Applies To

FPCBandwidthRules


FPCBandwidthRules.Remove Method

Removes a rule object from the collection.

Syntax

FPCBandwidthRules.Remove( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to remove.

Applies To

FPCBandwidthRules

See Also

FPCBandwidthRule


FPCBandwidthRules.Save Method

Saves all modified protocol rules to persistent storage.

Syntax

FPCBandwidthRules.Save()

Applies To

FPCBandwidthRules


FPCBandwidthRules.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCBandwidthRules collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCBandwidthRules.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCBandwidthRule


FPCCache Object

The FPCCache object is used to administer all cache configuration settings. Most details of the cache configuration are accessed by the CacheConfiguration and CacheContents properties of this object. The CacheConfiguration property returns an object of type FPCCacheConfiguration, and the CacheContents property returns an object of type FPCCacheContents.

FPCCache is a property of the FPCArray object.

Note to C++ Programmers

This object implements the IFPCCache interface.

Methods

The following table lists the methods of the FPCCache object.

Method | Description
Refresh | Reads the object from persistent storage, discarding any changes to the object that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCCache object.

Property | Description
CacheConfiguration | Returns an object that provides access to the cache configuration.
CacheContents | Returns an object for manipulating the contents of the cache.
ScheduledContentDownload | Returns a scheduled content download collection.
VendorParametersSets | The VendorParametersSets property returns a reference to an object for storing and loading custom data into the FPCCache object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCCache.CacheConfiguration Property

Returns an object that provides access to the cache configuration. This object is of type FPCCacheConfiguration.

Syntax

[ oFPCCacheConfiguration = ] FPCCache.CacheConfiguration

Possible Values

oFPCCacheConfiguration
Reference to an FPCCacheConfiguration object.

This property is read-only.

Applies To

FPCCache


FPCCache.CacheContents Property

Returns an object for reading the contents of the cache. This is done with a reference to an FPCCacheContents object, from which you can use the FetchURL method. This method allows you to force a pre-caching of sites.

Syntax

[ oFPCCacheContents = ] FPCCache.CacheContents

Possible Values

oFPCCacheContents
Reference to an FPCCacheContents object.

This property is read-only.

Applies To

FPCCache


FPCCache.Refresh Method

Reads the object from persistent storage, discarding any changes to the object that were not saved.

Syntax

FPCCache.Refresh()

Applies To

FPCCache


FPCCache.Save Method

Saves the object's configuration to persistent storage. It is important to remember that any changes made in scripts and programs will not be saved unless the Save method is called.

Syntax

FPCCache.Save()

Applies To

FPCCache


FPCCache.ScheduledContentDownload Property

Returns a scheduled content download collection.

Syntax

[ collFPCScheduledContentDownload = ] FPCCache.ScheduledContentDownload

Possible Values

collFPCScheduledContentDownload
Reference to an FPCScheduledContentDownload collection.

This property is read-only.

Applies To

FPCCache


FPCCache.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCCache object storage.

Syntax

[ collFPCVendorParametersSets = ] FPCCache.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCCache


FPCCacheConfiguration Object

The FPCCacheConfiguration object provides access to many ISA cache configuration settings because it is a container for the FPCActiveCacheConfiguration, FPCHTTPCacheConfiguration, and FPCFTPCacheConfiguration objects, which provide access to active, HTTP, and FTP object-caching configuration settings, respectively.

The FPCCacheConfiguration object is a property of the FPCCache object.

Note to C++ Programmers

This object implements the IFPCCacheConfiguration interface.

Methods

The following table lists the methods of the FPCCacheConfiguration object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.
ResetToDefaults | Discards any changes made to the cache configuration and reverts to the default cache configuration.
Save | Saves the cache configuration to persistent storage.

Properties

The following table lists the properties of the FPCCacheConfiguration object.

Property | Description
CacheQuestionUrls | Sets or retrieves whether caching of URLs that include the question mark is enabled or disabled.
Enabled | Sets or retrieves whether caching is enabled in the array.
FPCActiveCacheConfiguration | Retrieves a reference to an object for accessing the active cache configuration.
FTPConfiguration | Retrieves a reference to an object for accessing the FTP cache configuration.
HTTPConfiguration | Retrieves a reference to an object for accessing the HTTP cache configuration.
MaxProtectionTime | Sets or retrieves the maximum threshold (in minutes) after which the cached object would not be returned even if it expired before its ServerProtectionEnable property threshold passed.
ObjectSizeLimit | Sets or retrieves the maximum size of a cached object.
ServerProtectFactor | Sets or retrieves the time factor to which the policy set by the ServerProtectionEnable property applies.
ServerProtectionEnable | Sets or retrieves whether the Web proxy returns expired cached objects when an updated object cannot be retrieved, or whether to issue an error response.
SizeLimitEnable | Sets or retrieves whether the size limit specified by the ObjectSizeLimit property is enabled or disabled.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data in the FPCCacheConfiguration object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCCacheConfiguration.CacheQuestionUrls Property

Sets or retrieves whether caching of URLs that include the question mark is enabled or disabled.

Syntax

FPCCacheConfiguration.CacheQuestionUrls [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Caching of URLs with question mark is enabled.
FALSE | Caching of URLs with question mark is disabled.

The property is read-write.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.Enabled Property

Sets or retrieves whether caching is enabled in the array.

Syntax

FPCCacheConfiguration.Enabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of two settings:
Setting | Meaning
TRUE | Caching is enabled.
FALSE | Caching is disabled.

The property is read-write.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.FPCActiveCacheConfiguration Property

Retrieves a reference to an object for accessing the active cache configuration.

Syntax

[ oFPCActiveCacheConfiguration = ] FPCCacheConfiguration.FPCActiveCacheConfiguration

Possible Values

oFPCActiveCacheConfiguration
Reference to the FPCActiveCacheConfiguration object.

The property is read-only.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.FTPConfiguration Property

Retrieves a reference to an object for accessing the FTP cache configuration.

Syntax

[ oFPCFTPCacheConfiguration = ] FPCCacheConfiguration.FTPConfiguration

Possible Values

oFPCFTPCacheConfiguration
Reference to the FPCFTPCacheConfiguration object.

The property is read-only.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.HTTPConfiguration Property

Retrieves a reference to an object for accessing the HTTP cache configuration.

Syntax

[ oFPCHTTPCacheConfiguration = ] FPCCacheConfiguration.HTTPConfiguration

Possible Values

oFPCHTTPCacheConfiguration
Reference to the FPCHTTPCacheConfiguration object.

The property is read-only.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.MaxProtectionTime Property

Sets or retrieves the maximum time during which the expired cached object would be returned. MaxProtectionTime is for situations where a server cannot be reached to revalidate an expired cached object.

Syntax

FPCCacheConfiguration.MaxProtectionTime [ = lFactor ]

Possible Values

lFactor
Long value that specifies the maximum threshold. The maximum threshold is expressed in minutes.

The property is read-write.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.ObjectSizeLimit Property

Sets or retrieves the maximum size of an object that can be cached.

Syntax

FPCCacheConfiguration.ObjectSizeLimit [ = lMaxsize ]

Possible Values

lMaxsize
Long value that specifies the maximum size, in bytes, of a cached object.

The property is read-write.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.Refresh Method

Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.

Syntax

FPCCacheConfiguration.Refresh()

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.ResetToDefaults Method

Discards any changes made to the cache configuration and reverts to the default cache configuration.

Syntax

FPCCacheConfiguration.ResetToDefaults()

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.Save Method

Saves the cache configuration to persistent storage.

Syntax

FPCCacheConfiguration.Save()

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.ServerProtectFactor Property

Sets or retrieves the time factor to which the policy set by the ServerProtectionEnable property applies.

Syntax

FPCCacheConfiguration.ServerProtectFactor [ = lFactor ]

Possible Values

lFactor
Long value that specifies the time factor. The time factor is expressed as a percentage of the object's original Time to Live (TTL).

The property is read-write.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.ServerProtectionEnable Property

Sets or retrieves whether the Web proxy returns expired cached objects when an updated object cannot be retrieved, or whether to issue an error response.

Syntax

FPCCacheConfiguration.ServerProtectionEnable [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Web proxy returns expired cached objects.
FALSE | Web proxy issues an error response, but does not return expired cached objects.

The property is read-write.

Applies To

FPCCacheConfiguration

See Also

ServerProtectFactor


FPCCacheConfiguration.SizeLimitEnable Property

Sets or retrieves whether the size limit specified by the ObjectSizeLimit property is enabled or disabled.

Syntax

FPCCacheConfiguration.SizeLimitEnable [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of two settings:
Setting | Meaning
TRUE | Size limit is enabled.
FALSE | Size limit is disabled.

The property is read-write.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCCacheConfiguration object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCCacheConfiguration.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCCacheConfiguration


FPCCacheContents Object

The FPCCacheContents object is used to specify to the cache the URLs to be prefetched. This is achieved by using the FetchUrl method.

For more information about using FetchUrl, see Using FetchURL to Extend the Cache.

The ISA Server cache prefetching feature lets you download HTTP content directly to the ISA Server cache, upon request or as scheduled. Prefetching allows you to update the ISA Server cache with HTTP content that you anticipate will be requested by clients in your organization.

You can configure the content that ISA Server should precache. You can also schedule when the content should be cached, available for access directly from the ISA Server cache, rather than from the Internet.

You can use cache prefetching to schedule downloads of HTTP files from a Web site to a local cache. You can download a single URL, multiple URLs, or an entire Web site according to a schedule you specify.

The FPCCacheContents object is a property of the FPCCache object.

Note to C++ Programmers

This object implements the IFPCCacheContents interface.

Methods

The following table lists the methods of the FPCCacheContents object.

Method | Description
FetchUrl | Causes the Web proxy service to retrieve an object and store it in the cache.
Refresh | Reads from persistent storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCCacheContents.FetchUrl Method

Causes the Web proxy to retrieve an object and store it in the cache.

The Web proxy normally fetches objects from the Internet and caches them automatically as clients request them (passive caching). In addition, the Web proxy will automatically keep certain popular objects "fresh" within its cache by fetching them itself (active caching). However, there are occasions when an application needs a mechanism to override these automatic operations. The override lets the application exercise greater control either over the source of objects that are placed into the cache or the time they are to remain there. The FetchURL method allows you this greater degree of control.

To delete an HTTP object from the cache, set lpszFetchUrl = <empty string>, and lpszCacheUrl = <cachedURL>. When you delete an HTTP object by using FetchUrl, you can perform the operation synchronously or asynchronously, and the Time to Live (TTL) must be set to 0.

Syntax

FPCCacheContents.FetchUrl( lpszFetchUrl, lpszCacheUrl, lTtlInMinutes, lFlags )

Parameters

lpszFetchUrl
String that specifies the URL of the object to be fetched. The URL may be any combination of protocol, domain, and path that the Web proxy would normally be able to access. The Web proxy currently supports the HTTP, FTP, and gopher protocols. If sFetchUrl is an empty string then the FetchUrl method removes the value in CacheUrl from the cache.
lpszCacheUrl
String that specifies the URL that clients use to retrieve the fetched object from the Web proxy's cache. The URL must include one of the protocols supported by the Web proxy (HTTP, FTP or gopher), but the domain specified need not be accessible from the ISA server computer. This is because the data itself will have been read from the URL specified in the sFetchUrl parameter. The sCacheUrl parameter can be the same as the sFetchUrl parameter.
lTtlInMinutes
Long value that specifies the TTL, in minutes, that the object should be served from the Web proxy cache. After the TTL has passed, the object has "expired" and the Web proxy will not return it again to requesting clients unless the Web proxy first verifies that the object has not changed. In general, the application that calls FetchUrl needs to set a TTL large enough to ensure that the object will not expire before the application next refreshes it. Note that both fresh and expired objects can be deleted from the cache if the cache directories become full.

This parameter is ignored unless the lFlags parameter includes either the FETCH_TTL_IFNONE or FETCH_TTL_OVERRIDE flag. If neither flag is specified, the Web proxy's normal TTL computation mechanism is used for the object.

lFlags
Long value that specifies a set of bit flags to control the TTL of the object in the Web proxy's cache:
FETCH_TTL_OVERRIDE
Use the lTtlInMinutes parameter to set the TTL for the object regardless of any "Expires" or "Cache-Control: max-age" HTTP header that the publishing Web server may have included with the object. Be careful when overriding a TTL for objects that another party authored; overriding may cause objects to be cached longer than their intended lifetimes.
FETCH_TTL_IFNONE
The lTtlInMinutes parameter is used to set the TTL for the object unless the publishing Web server has supplied an "Expires" or "Cache-Control: max-age" HTTP header.

If you have set neither of these flags, the Web proxy uses its normal TTL computation mechanism for the object, which uses an "Expires" or "Cache-Control: max-age" HTTP header if available. Otherwise, the Web proxy estimates a good TTL value based on the time that has elapsed since the object was last modified.

In addition to the preceding flags, you can set one or more of the following flags:

FETCH_SYNCHRONOUS
This function does not return to the caller until the fetch has completed and you have stored the object in the cache, or until an error occurs in the processing of the request. Such an error ends the operation. If you do not specify this flag, the function returns immediately and the fetch completes asynchronously to the caller, in which case it is not possible to determine whether the fetch completed successfully.
FETCH_NO_ARRAY_ROUTING
If the ISA server is a member of an array, store this object in the cache of this particular proxy even if the normal array cache-sharing mechanism, the Cache Array Routing Protocol (CARP), indicates that the object should be cached on a different array member. If you do not specify this flag, the object is automatically cached on the array member that the CARP algorithm designates. This flag is ignored if the ISA server is not a member of an array.
FETCH_FORCE_CACHE
Cache the object even if the caching rules in the HTTP specification normally prohibit this object from being cached; for example, if the object contains a "Cache-Control: no-cache" HTTP header or the response indicates a server error. Be careful when using this flag for objects that were authored by another party. There is often a good reason why the data could not be cached and caching it might cause the site to function improperly or might even be a violation of your license agreement for use of the data. If the sCacheUrl parameter contains a question mark, this flag alone will not allow the object to be cached. Use the FPCCacheConfiguration.CacheQuestionUrls property to enable caching URLs containing question marks.

Applies To

FPCCacheContents


FPCCacheContents.Refresh Method

Reads the objects from persistent storage, discarding any changes to the collection that were not saved.

Syntax

FPCCacheContents.Refresh()

Applies To

FPCCacheContents


FPCCacheDrive Object

The FPCCacheDrive object represents a single cache drive of an ISA Server computer.

This object is a member of FPCCacheDrives collection.

Note to C++ Programmers

This object implements the IFPCCacheDrive interface.

Properties

The following table lists the properties of the FPCCacheDrive object.

Property | Description
CacheLimitInMegs | Sets or retrieves the disk size allocated to the cache.
Name | Retrieves the name of the drive.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCCacheDrive.CacheLimitInMegs Property

Sets or returns the disk size allocated to the cache.

Syntax

FPCCacheDrive.CacheLimitInMegs [ = lLimit ]

Possible Values

lLimit
Long value that specifies the disk size allocated to the cache, in megabytes.

The property is read-write.

Note

When you change the a cache allocation, the Web proxy (w3proxy) service must be restarted in order for your change to take effect. To stop and restart the w3proxy service use the FPCArray.SendRestartNotification Method.

Applies To

FPCCacheDrive


FPCCacheDrive.Name Property

Returns the name of the drive; for example, "C" or "D".

Syntax

[ sName = ] FPCCacheDrive.Name

Possible Values

sName
String that specifies the name of the drive.

The property is read-only.

Applies To

FPCCacheDrive


FPCCacheDrives Collection

The FPCCacheDrives collection provides access to a group of FPCCacheDrive objects. This collection is a property of the FPCServer object.

Note to C++ Programmers

This collection implements the IFPCCacheDrives interface.

Methods

The following table lists the methods of the FPCCacheDrives collection.

Method | Description
Add | Creates a new FPCCacheDrive object in the collection and returns a reference to it.
Item | Retrieves the given FPCCacheDrive object from the collection.
Refresh | Reads all the FPCCacheDrive objects from persistent storage, discarding any changes to the objects that were not saved.
Remove | Removes one FPCCacheDrive object from the collection.
Save | Saves all the FPCCacheDrive objects in the collection to persistent storage.

Properties

The following table lists the properties of the FPCCacheDrives collection.

Property | Description
Count | Retrieves the number of cache drive objects in the collection.
TotalCacheInMegs | Retrieves the total size allocated to the cache in all drives.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCCacheDrives collections storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCCacheDrives.Add Method

Creates a new FPCCacheDrive object in the collection and returns a reference to it. The Save method must be called in order for the additional FPCCacheDrive object to be saved to persistent storage.

Syntax

[ oFPCCacheDrive = ] FPCCacheDrives.Add( sName, lCacheLimitInMegs )

Parameters

sName
Required. String that specifies the name of the new cache drive.
lCacheLimitInMegs
Required. Long value that specifies the size, in megabytes, allocated to the cache in this particular drive.

Return Values

oFPCCacheDrive
Reference to the FPCCacheDrive object.

Applies To

FPCCacheDrives


FPCCacheDrives.Count Property

Retrieves the number of FPCCacheDrive objects in the collection.

Syntax

[ lCount = ] FPCCacheDrives.Count

Possible Values

lCount
Long value that specifies the number of cache drive objects.

The property is read-only.

Applies To

FPCCacheDrives


FPCCacheDrives.Item Method

Retrieves the given FPCCacheDrive object from the collection specified by the method's index parameter.

Syntax

[ vItem = ] FPCCacheDrives.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCCacheDrive. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCCacheDrives


FPCCacheDrives.Refresh Method

Reads all the FPCCacheDrive objects from persistent storage, discarding any changes to the objects that were not saved.

Syntax

FPCCacheDrives.Refresh()

Applies To

FPCCacheDrives


FPCCacheDrives.Remove Method

Removes one FPCCacheDrive object from the collection.

Syntax

FPCCacheDrives.Remove( vIndex )

Parameters

vIndex
Required. Name or one-based index of the FPCCacheDrive object to remove.

Note

When you remove a cache drive, and have saved changes by using the Save method, the Web proxy (w3proxy) service must be restarted in order for your change to take effect. To stop and restart the w3proxy service use the FPCArray.SendRestartNotification Method.

Applies To

FPCCacheDrives


FPCCacheDrives.Save Method

Saves all the FPCCacheDrive objects in the collection to persistent storage.

Syntax

FPCCacheDrives.Save()

Applies To

FPCCacheDrives


FPCCacheDrives.TotalCacheInMegs Property

Retrieves the total size allocated to the cache in all drives.

Syntax

[ lSize = ] FPCCacheDrives.TotalCacheInMegs

Possible Values

lSize
Long value that specifies the total size, in megabytes, allocated to the cache in all drives.

The property is read-only.

Applies To

FPCCacheDrives

See Also

FPCCacheDrive


FPCCacheDrives.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCCacheDrives collection's storage. The VendorParametersSets property allows third-party extensions to be integrated into ISA.

Syntax

[ collFPCVendorParametersSets = ] FPCCacheDrives.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCCacheDrives


FPCClientAddressSet Object

The FPCClientAddressSet object is a collection of FPCIpRange objects. Each FPCIpRange object defines a range of Internet protocols (IPs) with a lower and upper bound. As a collection of individual IP ranges, the FPCClientAddressSet object defines a set of IPs that is the union of all the ranges specified by each FPCIpRange object in the collection. FPCClientAddressSet objects are used as policy elements by ISA rules.

In the ISA administration tool, you will see the FPCClientAddressSet object listed as the policy element Client Address Sets.

FPCClientAddressSet is a member of an FPCClientAddressSets collection.

Note to C++ Programmers

This object implements the IFPCClientAddressSet interface.

Methods

The following table lists the methods of the FPCClientAddressSet object.

Method | Description
Add | Creates a new client object, inserts it into the collection, and returns a reference to it.
Item | Retrieves the given FPCIpRange object from the collection.
Refresh | Reads all of the items from persistent storage, discarding any changes to the current rules that were not saved.
Remove | Removes an IP mask from the collection.
Save | Saves all the items in the collection to persistent storage.

Properties

The following table lists the properties of the FPCClientAddressSet object.

Property | Description
Count | Retrieves the number of FPCIpRange objects in the collection.
Description | Sets or retrieves the description of the client set.
Name | Sets or retrieves the name of the client set.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCClientAddressSet object storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCClientAddressSet.Add Method

Creates a new client object, inserts it into the collection, and returns a reference to it.

Syntax

[ oFPCIpRange = ] FPCClientSet.Add( sIp_From, sIp_To )

Parameters

sIp_From
Required. String that specifies the lower bound of the IP range in x.y.z.t format.
sIp_To
Required. String that specifies the upper bound of the IP range, in x.y.z.t format.

Return Values

oFPCIpRange
Reference to the FPCIpRange object.

Applies To

FPCClientAddressSet


FPCClientAddressSet.Count Property

Retrieves the number of FPCIpRange objects in the collection.

Syntax

[ lCount = ] FPCClientSet.Count

Possible Values

lCount
Long value that specifies the number of FPCIpRange objects.

The property is read-only.

Applies To

FPCClientAddressSet


FPCClientAddressSet.Description Property

Sets or retrieves the description of the client set.

Syntax

FPCClientSet.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the client set.

The property is read-write.

Applies To

FPCClientAddressSet


FPCClientAddressSet.Item Method

Retrieves the given object from the collection.

Syntax

[ vItem = ] FPCClientSet.Item( vIpOrIndex, vMask, )

Parameters

vIpOrIndex
Required. One-based index, or lower-bound or single IP of the object to retrieve.
vIp_To
Optional. Higher-bound IP of the object to retrieve; needed if providing a lower-bound IP in vIpOrIndex.

Return Values

vItem
If successful, returns a reference to an object of type FPCIPRange. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCClientAddressSet


FPCClientAddressSet.Name Property

Sets or retrieves the name of the client set.

Syntax

FPCClientSet.Name [ = sName ]

Possible Values

sName
String that specifies the client set name.

The property is read-write.

Applies To

FPCClientAddressSet


FPCClientAddressSet.Refresh Method

Reads all the items from persistent storage, discarding any changes that were not saved.

Syntax

FPCClientSet.Refresh()

Applies To

FPCClientAddressSet


FPCClientAddressSet.Remove Method

Removes an FPCIpRange object from the collection.

Syntax

FPCClientSet.Remove( vIpOrIndex, vMask )

Parameters

ssIp_From
Required. One-based index, or lower-bound or single IP of the FPCIpRange object to remove.
vIp_To
Optional. Higher-bound IP of the object to retrieve; needed if providing a lower-bound IP in vIpOrIndex.

Applies To

FPCClientAddressSet


FPCClientAddressSet.Save Method

Saves all the items in the collection to persistent storage.

Syntax

FPCClientSet.Save()

Applies To

FPCClientAddressSet


FPCClientAddressSet.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCClientAddressSet object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCClientSet.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCClientAddressSet


FPCClientAddressSets Collection

The FPCClientAddressSets collection provides access to a group of FPCClientAddressSet objects. Each object within this collection defines a set of client IPs used by a rule. Each client IP within the set is stored in an FPCIpRange object.

The FPCClientAddressSets collection is a property of an FPCPolicyElements object.

Note to C++ Programmers

This collection implements the IFPCClientAddressSets interface.

Methods

The following table lists the methods of the FPCClientAddressSets collection.

Method | Description
Add | Creates a new client set, inserts it into the collection, and returns a reference to it.
Item | Retrieves the given FPCClientAddressSet object from the collection.
Refresh | Reads all the FPCClientAddressSet objects from persistent storage, discarding any changes to the objects that were not saved.
Remove | Removes a client set from the collection.
Save | Saves all the items in the collection to persistent storage.

Properties

The following table lists the properties of the FPCClientAddressSets collection.

Property | Description
Count | Retrieves the number of FPCClientAddressSet objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCClientAddressSets collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCClientAddressSets.Add Method

Creates a new client set, inserts it into the collection, and returns a reference to it.

Syntax

[ oFPCClientSet = ] FPCClientAddressSets.Add( sName )

Parameters

sName
Required. String that specifies the name of the new set.

Return Values

oFPCClientSet
Returns a reference to the new FPCClientAddressSet object.

Applies To

FPCClientAddressSets


FPCClientAddressSets.Count Property

Retrieves the number of FPCClientAddressSet objects in the collection.

Syntax

[ lCount = ] FPCClientAddressSets.Count

Possible Values

lCount
Long value that specifies the number of FPCClientAddressSet objects.

The property is read-only.

Applies To

FPCClientAddressSets


FPCClientAddressSets.Item Method

Retrieves the given FPCClientAddressSet object from the collection.

Syntax

[ vItem = ] FPCClientAddressSets.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCClientAddressSet. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCClientAddressSets


FPCClientAddressSets.Refresh Method

Reads all the FPCClientAddressSet objects from persistent storage, discarding any changes to the objects that were not saved.

Syntax

FPCClientAddressSets.Refresh()

Applies To

FPCClientAddressSets


FPCClientAddressSets.Remove Method

Removes a client set from the collection.

Syntax

FPCClientAddressSets.Remove( vIndex )

Parameters

vIndex
Required. Name or one-based index of the FPCClientAddressSet object to remove.

Applies To

FPCClientAddressSets


FPCClientAddressSets.Save Method

Saves all the items in the collection to persistent storage.

Syntax

FPCClientAddressSets.Save()

Applies To

FPCClientAddressSets


FPCClientAddressSets.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCClientAddressSets collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCClientAddressSets.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCClientAddressSets


FPCClientAutoScript Object

The FPCClientAutoScript object represents the properties of the automatic script used by browsers to work efficiently with multiple servers in a domain array.

You can set an option for the opening of a Web browser by a client, so that ISA automatically downloads a client configuration script located on the ISA Server computer. This script is downloaded to the browser on a client computer and is executed against every URL that the browser requests. This takes away some of the routing work that members of an ISA server domain array usually perform. The output of this script provides an ordered series of ISA servers that the browser uses to retrieve the object specified by the URL. The script is stored at a specific URL on any ISA server in a domain array. You can easily update all Web browser settings without having to reconfigure each individual Web browser.

Alternatively, you can construct your own configuration script and place it on your Web server. When a Web browser looks for the configuration script, your Web server intercepts the request and returns the custom script to the browser.

The FPCClientAutoScript object is a property of the FPCWebBrowserClientConfig object.

Note to C++ Programmers

This object implements the IFPCClientAutoScript interface.

Methods

The following table lists the methods of the FPCClientAutoScript object.

Method | Description
Refresh | Reads the automatic script information from persistent storage, discarding any changes to the current object that were not saved.
Save | Saves the automatic script properties to persistent storage.

Properties

The following table lists the properties of the FPCClientAutoScript object.

Property | Description
BackupRoute | Returns the client backup route.
BypassLocalServers | Sets or returns whether a client will bypass the Web proxy for requests that do not include a dot.
DirectAddressDestinations | Returns a reference to the FPCDirectAddressDestinations collection.
DirectIpDestinations | Returns a reference to the FPCDirectIpDestinations collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCClientAutoScript.BackupRoute Property

Returns the client backup route.

Syntax

[ oFPCClientBackupRoute = ] FPCClientAutoScript.BackupRoute

Return Value

oFPCClientBackupRoute
Returns a reference to an FPCClientBackupRoute object.

This property is read-only.

Applies To

FPCClientAutoScript


FPCClientAutoScript.BypassLocalServers Property

Sets or returns whether a client will bypass the Web proxy for requests that do not include a dot.

Syntax

FPCClientAutoScript.BypassLocalServers ( = bBypass )

Possible Values

bBypass
Boolean value thatspecifies whether a client will bypass the Web proxy for requests that do not include a dot.

Return Values

oFPCClientBackupRoute
Returns a reference to an FPCClientBackupRoute object.

This property is read-write.

Applies To

FPCClientAutoScript


FPCClientAutoScript.DirectAddressDestinations Property

Returns a reference to the FPCDirectAddressDestinations collection.

Syntax

[ collFPCDirectAddressDestinations = ] FPCClientAutoScript.DirectAddressDestinations

Return Value

collFPCDirectAddressDestinations
Reference to the FPCDirectAddressDestinations collection.

This property is read-only.

Applies To

FPCClientAutoScript


FPCClientAutoScript.DirectIpDestinations Property

Returns a reference to the FPCDirectIpDestinations collection.

Syntax

[ collFPCDirectIpDestinations = ] FPCClientAutoScript.DirectIpDestinations

Return Value

collFPCDirectIpDestinations
Reference to the FPCDirectIpDestinations collection.

This property is read-only.

Applies To

FPCClientAutoScript


FPCClientAutoScript.Refresh Method

Reads the automatic script information from persistent storage, discarding any changes to the current object that were not saved.

Syntax

FPCClientAutoScript.Refresh()

Applies To

FPCClientAutoScript


FPCClientAutoScript.Save Method

Saves the automatic script properties to persistent storage.

Syntax

FPCClientAutoScript.Save()

Applies To

FPCClientAutoScript


FPCClientBackupRoute Object

The FPCClientBackupRoute object represents the backup route information in the Web browser client configuration of the ISA domain array.You can define a backup route for Web browser clients, so that if the ISA server is available, the client will have either direct Web access, or access through an alternate server. This object is a property of the FPCClientAutoScript object.

Note to C++ Programmers

This object implements the IFPCClientBackupRoute interface.

Methods

The following table lists the methods of the FPCClientBackupRoute object.

Method | Description
Refresh | Reads the backup route information from persistent storage, discarding any changes to the current object that were not saved.
Save | Saves the backup route information to persistent storage.

Properties

The following table lists the properties of the FPCClientBackupRoute object.

Property | Description
AutoConfigBackupRoute | Sets or retrieves the backup route.
ClientBackupRouteType | Sets or retrieves the type of the backup route. It can be either direct to the Internet or by proxy.
Enabled | Sets or retrieves whether the option of backup route in the Web proxy client is enabled or disabled.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCClientBackupRoute.AutoConfigBackupRoute Property

Sets or retrieves the backup route.

Syntax

FPCClientBackupRoute.AutoConfigBackupRoute [ = sType ]

Possible Values

sType
String that specifies the backup route. "DIRECT" means that the backup route is directly to the Internet rather than through an alternate proxy server.

The property is read-write.

Applies To

FPCClientBackupRoute


FPCClientBackupRoute.ClientBackupRouteType Property

Sets or retrieves the type of the backup route. It can be either direct to the Internet or by proxy.

Syntax

FPCClientBackupRoute.ClientBackupRouteType [ = FpcBackupRouteType ]

Possible Values

FpcClientBackupRouteType
The backup route type can have a value from the FpcClientBackupRouteType enumerated type.

The property is read-write.

Applies To

FPCClientBackupRoute


FPCClientBackupRoute.Enabled Property

Sets or retrieves whether the option of backup route in the Web proxy client is enabled or disabled.

Syntax

FPCClientBackupRoute.Enabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Option of backup route in the Web proxy client is enabled.
FALSE | Option of backup route in the Web proxy client is disabled.

The property is read-write.

Applies To

FPCClientBackupRoute


FPCClientBackupRoute.Refresh Method

Reads the backup route information from persistent storage, discarding any changes to the current object that were not saved.

Syntax

FPCClientBackupRoute.Refresh()

Applies To

FPCClientBackupRoute


FPCClientBackupRoute.Save Method

Saves the backup route information to persistent storage.

Syntax

FPCClientBackupRoute.Save()

Applies To

FPCClientBackupRoute


FPCClientConfigSettings Collection

The FPCClientConfigSettings collection provides access to a group of FPCClientSettingsSection objects. Each FPCClientSettingsSection object contains sections of client settings.

The FPCClientAddressSets collection is a property of the FPCPolicyElements object.

Note

When you've changed client configuration settings, the firewall service must be restarted in order for your change to take effect. To stop and restart the firewall service use the FPCArray.SendRestartNotification Method.

Note to C++ Programmers

This collection implements the IFPCClientConfigSettings interface.

Methods

The following table lists the methods of the FPCClientConfigSettings collection.

Method | Description
AddSection | Adds a client settings section to the collection.
Item | Returns the given FPCClientSettingsSection object from the collection.
Refresh | Reads all the FPCClientSettingsSection objects from persistent storage, discarding any changes to the objects that were not saved.
Remove | Removes a client settings section from the collection.
Save | Saves all the items in the collection to persistent storage.

Properties

The following table lists the properties of the FPCClientConfigSettings collection.

Property | Description
Count | Retrieves the number of FPCClientSettingsSection objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCClientConfigSettings.AddSection Method

Creates a new client settings section, inserts it into the collection, and returns a reference to it.

Syntax

[ oFPCClientSettingsSection = ] FPCClientConfigSettings.AddSection( sName )

Parameters

sName
Required. String that specifies the name of the new section.

Return Values

oFPCClientSettingsSectiont
Returns a reference to the new FPCClientSettingsSection object.

Applies To

FPCClientConfigSettings


FPCClientConfigSettings.Item Method

Returns the given FPCClientSettingsSection object from the collection.

Syntax

[ vItem = ] FPCClientConfigSettings.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCClientSettingsSection. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.


FPCClientConfigSettings.Count Property

Retrieves the number of FPCClientSettingsSection objects in the collection.

Syntax

[ lCount = ] FPCClientConfigSettings.Count

Possible Values

lCount
Long value that specifies the number of FPCClientSettingsSection objects.

The property is read-only.

Applies To

FPCClientConfigSettings


FPCClientConfigSettings.Refresh Method

Reads all the FPCClientSettingsSection objects from persistent storage, discarding any changes to the objects that were not saved.

Syntax

FPCClientConfigSettings.Refresh()

Applies To

FPCClientConfigSettings


FPCClientConfigSettings.Remove Method

Removes a client settings section from the collection.

Syntax

FPCClientConfigSettings.Remove( vIndex )

Parameters

vIndex
Required. Name or one-based index of the FPCClientSettingsSection object to remove.

Applies To

FPCClientConfigSettings


FPCClientConfigSettings.Save Method

Saves all the items in the collection to persistent storage.

Syntax

FPCClientConfigSettings.Save()

Applies To

FPCClientConfigSettings


FPCClientSettingsSection Object

The FPCClientSettingsSection object contains sections of client settings. These sections, together with the Local Domain Table (LDT) and the client-configuration options, comprise the information stored in mspclnt.ini, the global client configuration file. By storing the sections in the FPCClientSettingsSection object, the client configuration information will be shared and synchronized between ISA Server arrays.

For more information on mspclnt.ini, see the ISA Server product documentation.

FPCClientSettingsSection is a member of an FPCClientConfigSettings collection.

Note

When you've changed client settings, the firewall service must be restarted in order for your change to take effect. To stop and restart the firewall service use the FPCArray.SendRestartNotification Method.

Note to C++ Programmers

This object implements the IFPCClientSettingsSection interface.

Methods

The following table lists the methods of the FPCClientSettingsSection object.

Method | Description
Refresh | Reads all of the items from persistent storage, discarding any changes to the current rules that were not saved.
RemoveValue | Removes a client settings value from the collection.
Save | Saves all the items in the collection to persistent storage.

Properties

The following table lists the properties of the FPCClientSettingsSection object.

Property | Description
AllNames | Returns all the names of the client settings.
Value | Sets or returns the value associated with the given name.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCClientSettingsSection.AllNames Property

Returns all the names of the client settings section.

Syntax

[ pItem = ]FPCClientSettingsSection.AllNames

Possible Values

pItem
Pointer to a domain array of strings.

The property is read-only.

Remarks

The AllNames property returns a list of all the names of client settings stored through the Value property.

Applies To

FPCClientSettingsSection


FPCClientSettingsSection.Refresh Method

Reads all the items from persistent storage, discarding any changes that were not saved.

Syntax

FPCClientSettingsSection.Refresh()

Applies To

FPCClientSettingsSection


FPCClientSettingsSection.RemoveValue Method

Removes a client setting value from the list of client settings.

Syntax

FPCClientSettingsSection.RemoveValue(sName)

Parameters

sName
Required. String that specifies the name of the value to be removed.

Applies To

FPCClientSettingsSection


FPCClientSettingsSection.Save Method

Saves the client settings section to persistent storage.

Syntax

FPCClientSettingsSection.Save()

Applies To

FPCClientSettingsSection


FPCClientSettingsSection.Value Property

Sets or returns the value associated with the given name.

Syntax

FPCClientSettingsSection.Value (Name)[ = Value ]

Possible Values

Name
Specifies the parameter name for which to retrieve the value. The name can be of almost any type and is not necessarily a string.

The property is read-write.

Remarks

The FPCClientSettingsSection object is used to store data that is defined as {name, value} pairs using the Value property. The following example stores a property named x having a value of 1:

FPCClientSettingsSection.Value("x") = 1

The phrase Value("x") will return the value.

Applies To

FPCClientSettingsSection


FPCContentGroup Object

The FPCContentGroup object describes and provides access to the content-type groups that an FPCSiteAndContentRule object can reference. The default content-type groups are Audio, Executable, Images, Text, and Video. Each group includes file types. If you want to change the file types that are included in a group, do so through this object. You can also create additional content groups.

The FPCContentGroup object is a member of the FPCContentGroups collection.

Note to C++ Programmers

This object implements the IFPCContentGroup interface.

Methods

The following table lists the methods of the FPCContentGroup object.

Method | Description
Add | Adds a new file type or MIME content type to the collection and returns a reference to it.
Item | Retrieves the given content type object from the collection.
Refresh | Reads all the content types from persistent storage, discarding any changes to the current types that were not saved.
Remove | Removes a content type from the collection.
RemoveAll | Clears the list.
Save | Saves the content group to persistent storage.

Properties

The following table lists the properties of the FPCContentGroup object.

Property | Description
Count | Retrieves the number of content types in the collection.
Description | Sets or retrieves the description of the group.
Name | Sets or retrieves the name of the group.
VendorParametersSets | Retrieves a reference to an object for storing and loading of custom data into the FPCContentGroup object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCContentGroup.Add Method

Adds a new MIME content type to the collection and returns a reference to it.

Syntax

FPCContentGroup.Add( sNewType )

Parameters

sNewType
Required. String that specifies the name of the new MIME content type.

Applies To

FPCContentGroup


FPCContentGroup.Count Property

Retrieves the number of content types in the collection.

Syntax

[ lCount = ] FPCContentGroup.Count

Possible Values

lCount
Long value that specifies the number of content types.

The property is read-only.

Applies To

FPCContentGroup


FPCContentGroup.Description Property

Sets or retrieves the description of the group.

Syntax

FPCContentGroup.Description [ = sDesc ]

Possible Values

sDesc
String that specifies the group description.

The property is read-write.

Applies To

FPCContentGroup


FPCContentGroup.Item Method

Retrieves the given content type object from the collection.

Syntax

[ vItem = ] FPCContentGroup.Item( lIndex )

Parameters

lIndex
Required. Long value that contains the name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns the given content type object from the collection. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCContentGroup


FPCContentGroup.Name Property

Sets or retrieves the name of the group.

Syntax

FPCContentGroup.Name [ = sName ]

Possible Values

sName
String that specifies the group name.

The property is read-write.

Applies To

FPCContentGroup


FPCContentGroup.Refresh Method

Reads all the content types from persistent storage, discarding any changes to the current types that were not saved.

Syntax

FPCContentGroup.Refresh()

Applies To

FPCContentGroup


FPCContentGroup.Remove Method

Removes a MIME content type from the object.

Syntax

FPCContentGroup.Remove( sType )

Parameters

sType
Required. String that specifies the name of the MIME content type to remove.

Applies To

FPCContentGroup


FPCContentGroup.RemoveAll Method

Removes all of the content types from the object.

Syntax

FPCContentGroup.RemoveAll( )

Applies To

FPCContentGroup


FPCContentGroup.Save Method

Saves the content group to persistent storage.

Syntax

FPCContentGroup.Save()

Applies To

FPCContentGroup


FPCContentGroup.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCContentGroup object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCContentGroup.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

This property is read-only.

Applies To

FPCContentGroup


FPCContentGroups Collection

The FPCContentGroups collection provides access to a group of content collections, each represented by an individual FPCContentGroup object. This object is a property of the FPCPolicyElements object.

Note to C++ Programmers

This collection implements the IFPCContentGroups interface.

Methods

The following table lists the methods of the FPCContentGroups collection.

Method | Description
Add | Creates a new FPCContentGroup object.
Item | Retrieves the given FPCContentGroup object from the collection.
Refresh | Reads all items from persistent storage, discarding any changes to the current changes that were not saved.
Remove | Removes an FPCContentGroup object from the collection.
Save | Saves all items in the collection to persistent storage.

Properties

The following table lists the properties of the FPCContentGroups collection.

Property | Description
Count | Retrieves the number of content group objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading of custom data into the FPCDestinationSets collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCContentGroups.Add Method

Creates a new FPCContentGroup object in the collection and returns a reference to it.

Syntax

[ oFPCContentGroup = ] FPCContentGroups.Add( sName )

Parameters

sName
Required. String that specifies the name of the new destination set.

Return Value

oFPCContentGroup
Reference to an FPCContentGroup object.

Applies To

FPCContentGroups

See Also

FPCContentGroup


FPCContentGroups.Count Property

Retrieves the number of content group objects in the collection.

Syntax

[ lCount = ] FPCContentGroups.Count

Possible Values

lCount
Long value that specifies the number of destination set objects.

The property is read-only.

Applies To

FPCContentGroups

See Also

FPCContentGroup


FPCContentGroups.Item Method

Retrieves a given FPCContentGroup object from the collection.

Syntax

[ vItem = ] FPCContentGroups.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCContentGroup. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCContentGroups


FPCContentGroups.Refresh Method

Reads all the items from persistent storage, discarding any changes that were not saved.

Syntax

FPCContentGroups.Refresh()

Applies To

FPCContentGroups


FPCContentGroups.Remove Method

Removes a content group object from the collection.

Syntax

FPCContentGroups.Remove( vItem )

Parameters

vItem
Required. One-based index of the object to remove.

Applies To

FPCContentGroups

See Also

FPCContentGroup


FPCContentGroups.Save Method

Saves all the items in the collection to persistent storage.

Syntax

FPCContentGroups.Save()

Applies To

FPCContentGroups


FPCContentGroups.VendorParametersSets Property

Retrieves a reference to an object for storing and loading of custom data into the FPCContentGroups collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCContentGroups.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCContentGroups


FPCCredentials Object

The FPCCredentials object lets you set the user name and password to be used when an ISA Server computer communicates with an upstream proxy server. For example, chaining with another proxy server computer can require that the user name and password have been checked before chaining takes place. A routing rule that routes requests to an upstream proxy server can also check the user name and password before routing the request.

The FPCCredentials object is a property of the FPCPrimaryRoute and FPCBackupRoute objects.

Note to C++ Programmers

This object implements the IFPCCredentials interface.

Methods

The following table lists the methods of the FPCCredentials object.

Method | Description
Refresh | Reads the credentials from persistent storage, discarding any changes that were not saved.
Save | Saves the credentials to persistent storage.

Properties

The following table lists the properties of the FPCCredentials object.

Property | Description
Password | Sets or retrieves the password.
UserName | Sets or retrieves the user name.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCCredentials.Password Property

Sets the password.

Syntax

FPCCredentials.Password [ = sPassword ]

Possible Values

sPassword
String that specifies the password.

The property is write-only.

Applies To

FPCCredentials


FPCCredentials.Refresh Method

Reads the credentials from persistent storage, discarding any changes that were not saved.

Syntax

FPCCredentials.Refresh()

Applies To

FPCCredentials


FPCCredentials.Save Method

Saves the credentials to persistent storage.

Syntax

FPCCredentials.Save()

Applies To

FPCCredentials


FPCCredentials.UserName Property

Sets or retrieves the user name.

Syntax

FPCCredentials.UserName [ = sUserName ]

Possible Values

sUserName
String that specifies the user name.

The property is read-write.

Remarks

When this object is used in the context of logging to a database, the user name will be in domain\account format or in SQL password format.

Applies To

FPCCredentials


FPCDestination Object

The FPCDestination object represents a destination that the Web proxy can access. Destinations are grouped in an FPCDestinationSet collection, which you can use to define site and content rules, publishing rules, or routing rules. For example, you can create a destination set that contains sport sites, and define a rule that prohibits access to these destinations during work hours.

A destination consists of two parts — a host description and a path within this host. For example, in "www.microsoft.com/scripting", "www.microsoft.com" is the host and "scripting" is the path. A host can be specified by domain name, IP address, or an IP range denoted by a From and To pair of settings.

An FPCDestination object is a member of an FPCDestinationSet collection.

Note to C++ Programmers

This object implements the IFPCDestination interface.

Methods

The following table lists the methods of the FPCDestination object.

Method | Description
SetDestinationAsDomain | Sets the host definition by stating a host name.
SetDestinationAsIpRange | Sets the host definition by stating a range of IP addresses.
SetDestinationAsSingleIP | Sets the host definition by stating its IP address.

Properties

The following table lists the properties of the FPCDestination object.

Property | Description
DomainCpid | Retrieves the domain that corresponds to the code page ID (Cpid) of a URL
DomainName | Retrieves the destination host name; for example, "www.microsoft.com".
Ip_From | Retrieves the host's IP address.
Ip_To | Retrieves the host's mask.
Path | Sets or retrieves the host's path.
PathCpid | Retrieves the path that corresponds to the code page ID (Cpid) of a URL
Type | Returns the destination type.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCDestination object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDestination.DomainCpid Property

Retrieves the domain that corresponds to the code page ID (Cpid) of a URL. The Cpid is useful if a URL string contains national characters that are not ANSI standard; for example, a URL string containing Japanese characters.

Syntax

[ Domain = ] FPCDestination.DomainCpid

Possible Values

Domain
Reference to the domain that corresponds to the code page ID (Cpid) of a URL.

The property is read-only.

Applies To

FPCDestination


FPCDestination.DomainName Property

Retrieves the destination host name; for example, "www.microsoft.com".

Syntax

[ sName = ] FPCDestination.DomainName

Possible Values

sName
String that specifies the destination host name.

The property is read-only. It can be set by calling the SetDestinationAsDomain method.

Applies To

FPCDestination


FPCDestination.Ip_From Property

Retrieves the host's IP address.

Syntax

[ sIp_From = ] FPCDestination.Ip_From

Possible Values

sIp_From
String that specifies the host's IP address.

The property is read-only.

Remarks

This property is valid only if the host definition was set by the SetDestinationAsSingleIP or SetDestinationAsIpRange method.

Applies To

FPCDestination


FPCDestination.Ip_To Property

Retrieves the host's mask.

Syntax

[ sIp_To = ] FPCDestination.Ip_To

Possible Values

sIp_To
String that specifies the host's mask.

The property is read-only.

Remarks

This property is valid only if the host definition was set by the SetDestinationAsIpRange method.

Applies To

FPCDestination


FPCDestination.Path Property

Sets the host's path. A path must start with a '/'. For example : /Images/*

Syntax

[ sPath = ] FPCDestination.Path

Possible Values

sPath
String that specifies the path.

The property is read-only. It can be set by calls to the SetDestinationAsIpRange, SetDestinationAsSingleIP, or SetDestinationAsDomain methods.

Applies To

FPCDestination


FPCDestination.PathCpid Property

Retrieves the path that corresponds to the code page ID (Cpid) of a URL. The Cpid is useful if a URL string contains national characters that are not ANSI standard; for example, a URL string containing Japanese characters.

Syntax

[ Path = ] FPCDestination.PathCpid

Possible Values

Path
Reference to the path that corresponds to the code page identifier (Cpid) of a URL.

The property is read-only.

Applies To

FPCDestination


FPCDestination.SetDestinationAsDomain Method

Sets the host definition by stating a host name.

Syntax

FPCDestination.SetDestinationAsDomain( Domain, Path, CpidDomain, CpidPath)

Parameters

Domain
Required. String that specifies the domain to be used.
Path
Optional. Specifies the path property of the object to be removed.
CpidDomain
Optional. Specifies the code page for the domain string.
CpidPath
Optional. Specifies the code page for the path string.

Applies To

FPCDestination


FPCDestination.SetDestinationAsIpRange Method

Sets the host definition by stating a range of IP addresses.

Syntax

FPCDestination.SetDestinationAsIpRange( sIp_FromStr, sIp_ToStr, Path, CpidPath )

Parameters

sIp_FromStr
Required. String that specifies the starting IP address in x.y.z.t format.
sIp_ToStr
Required. String that specifies the ending IP address in x.y.z.t format.
Path
Optional. Specifies the path property of the object to be removed.
CpidPath
Optional. Specifies the code page for the path string.

Applies To

FPCDestination


FPCDestination.SetDestinationAsSingleIP Method

Sets the host definition by stating its IP address.

Syntax

FPCDestination.SetDestinationAsSingleIP( sIpStr, Path, CpidPath )

Parameters

sIpStr
Required. String that specifies the IP address in x.y.z.t format.
Path
Optional. Specifies the path property of the object to be removed.
CpidPath
Optional. Specifies the code page for the path string.

Applies To

FPCDestination


FPCDestination.Type Property

Returns the destination type. The type can be a domain, a single IP address, or a range of IP addresses.

Syntax

[ DestType = ] FPCDestination.Type

Possible Values

DestType

A value from the FpcDestinationAddressType enumeration.

The property is read-only.

Applies To

FPCDestination


FPCDestination.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCDestination object's storage. The VendorParametersSets property is designed to allow third-party extensions to be integrated into ISA.

Syntax

[ collCometVendorParametersSets = ] FPCDestination.VendorParametersSets

Possible Values

collCometVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCDestination


FPCDestinationSet Collection

The FPCDestinationSet collection defines a set of destinations stored as FPCDestination objects. The rules of an ISA server use these destinations.

You use an FPCDestinationSet collection to define site and content rules, publishing rules, and routing rules. For example, you could create a destination set containing sport sites, and define a rule that prohibited access to these destinations during work hours.

A destination consists of two parts — a host description and a path within this host. For example, in "www.microsoft.com/scripting", "www.microsoft.com" is the host and "scripting" is the path. A host can be specified by domain name, IP address, or an IP range denoted by a From and To pair of settings.

This collection is a member of the FPCDestinationSets collection.

Note to C++ Programmers

This collection implements the IFPCDestinationSet interface.

Methods

The following table lists the methods of the FPCDestinationSet collection.

Method | Description
Add | Creates a new FPCDestination object in the collection and returns a reference to it.
Item | Retrieves the given FPCDestination object from the collection.
Refresh | Reads all the items from persistent storage, discarding any changes that were not saved.
Remove | Removes a destination object from the collection.
Save | Saves all the items in the collection to persistent storage.

Properties

The following table lists the properties of the FPCDestinationSet collection.

Property | Description
Count | Retrieves the number of destination objects in the collection.
Description | Sets or retrieves the description of the set.
Name | Sets or retrieves the name of the destination set.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCDestinationSet collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDestinationSet.Add Method

Creates a new FPCDestination object in the collection and returns a reference to it. The Save method must be called for the new FPCDestinationSet collection to be saved in persistent storage.

Syntax

[ oFPCDestination = ] FPCDestinationSet.Add( sDomain, vIp_To, sPath, lCpidDomain, lCpidPath )

Parameters

sDomain
Required. String that specifies the domain for the new destination. It can be a domain name or an IP address.
vIp_To
Optional. String that specifies an IP upper bound that defines the destination as an IP range pair using this value and the value of the IP parameter. This parameter should be supplied only if the previous parameter is an IP address.
sPath
Optional. String value that specifies the path property of the destination to be added. A path must start with a '/'. For example, /Images/*
lCpidDomain
Optional. Long value that specifies the code page identifier (Cpid) of the domain.
lCpidPath
Optional. Long value that specifies the Cpid of the path.

Return Values

oFPCDestination
Reference to the FPCDestination object.

Applies To

FPCDestinationSet


FPCDestinationSet.Count Property

Retrieves the number of FPCDestination objects in the collection.

Syntax

[ iCount = ] FPCDestinationSet.Count

Possible Values

iCount
Integer value that specifies the number of destination objects.

The property is read-only.

Applies To

FPCDestinationSet


FPCDestinationSet.Description Property

Sets or retrieves the description of the set.

Syntax

FPCDestinationSet.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description.

The property is read-write.

Applies To

FPCDestinationSet


FPCDestinationSet.Item Method

Retrieves the given FPCDestination object from the collection.

Syntax

[ vItem = ] FPCDestinationSet.Item( vIndex, Ip_From, Path )

Parameters

vIndex
Required. One-based index of the object to retrieve, or domain name or lower-bound IP.
sIp_To
Optional. String that specifies the higher-bound IP of the object to retrieve; needed if providing a lower-bound IP in vIndex. .
sPath
Optional. String that specifies the path property of the object.

Return Value

vItem
If successful, returns a reference to an object of type FPCDestination. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCDestinationSet


FPCDestinationSet.Name Property

Sets or retrieves the name of the destination set.

Syntax

FPCDestinationSet.Name [ = sName ]

Possible Values

sName
String that specifies the name.

The property is read-write.

Applies To

FPCDestinationSet


FPCDestinationSet.Refresh Method

Reads all the items from persistent storage, discarding any changes that were not saved.

Syntax

FPCDestinationSet.Refresh()

Applies To

FPCDestinationSet


FPCDestinationSet.Remove Method

Removes a destination object from the collection.

Syntax

FPCDestinationSet.Remove( vIndex, vIp_To, Path )

Parameters

vIndex
Required. One-based index of the object to remove, or a string representing the object to remove. A string can be a domain name (for example, www.microsoft.com), or an IP address of the format x.y.z.t.
vIp_To
Optional. String that specifies the higher-bound IP of the object to retrieve; needed if providing a lower-bound IP in vIndex.
Path
Optional. Specifies the path property of the object to be removed.

Applies To

FPCDestinationSet

See Also

FPCDestination


FPCDestinationSet.Save Method

Saves all items in the collection to persistent storage.

Syntax

FPCDestinationSet.Save()

Applies To

FPCDestinationSet


FPCDestinationSet.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCDestinationSet collection's storage. The VendorParametersSets property is designed to allow third-party extensions to be integrated into ISA.

Syntax

[ collFPCVendorParametersSets = ] FPCDestinationSet.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCDestinationSet


FPCDestinationSets Collection

The FPCDestinationSets collection provides access to a group of destination sets stored as FPCDestinationSet collections. You use these destination sets to define site and content rules, publishing rules, and routing rules.

This object is a property of an FPCPolicyElements object.

Note to C++ Programmers

This collection implements the IFPCDestinationSets interface.

Methods

The following table lists the methods of the FPCDestinationSets collection.

Method | Description
Add | Creates a new FPCDestinationSet collection.
Item | Retrieves the given FPCDestinationSet collection from the collection.
Refresh | Reads all the items from persistent storage, discarding any changes that were not saved.
Remove | Removes a destination set object from the collection.
Save | Saves all the items in the collection to persistent storage.

Properties

The following table lists the properties of the FPCDestinationSets collection.

Property | Description
Count | Retrieves the number of destination set objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCDestinationSets collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDestinationSets.Add Method

Creates a new FPCDestinationSet collection in the FPCDestinationSets collection and returns a reference to it. The Save method must be called for the new FPCDestinationSet collection to be saved to persistent storage.

Syntax

[ collFPCDestinationSet = ] FPCDestinationSets.Add( sName )

Parameters

sName
Required. String that specifies the name of the new destination set.

Return Value

collFPCDestinationSet
Reference to the FPCDestinationSet collection.

Applies To

FPCDestinationSets


FPCDestinationSets.Count Property

Retrieves the number of destination set objects in the collection.

Syntax

[ iCount = ] FPCDestinationSets.Count

Possible Values

iCount
Integer value that specifies the number of destination set objects.

The property is read-only.

Applies To

FPCDestinationSets

See Also

FPCDestinationSet


FPCDestinationSets.Item Method

Retrieves the given FPCDestinationSet collection from the FPCDestinationSets collection.

Syntax

[ vItem = ] FPCDestinationSets.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCDestinationSet. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCDestinationSets


FPCDestinationSets.Refresh Method

Reads all the items from persistent storage, discarding any changes that were not saved.

Syntax

FPCDestinationSets.Refresh()

Applies To

FPCDestinationSets


FPCDestinationSets.Remove Method

Removes a destination set object from the collection.

Syntax

FPCDestinationSets.Remove( vItem )

Parameters

vItem
Required. One-based index of the object to remove.

Applies To

FPCDestinationSets

See Also

FPCDestinationSet


FPCDestinationSets.Save Method

Saves all the FPCDestinationSet objects in the collection to persistent storage.

Syntax

FPCDestinationSets.Save()

Applies To

FPCDestinationSets


FPCDestinationSets.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCDestinationSets collection's storage. The VendorParametersSets property is designed to allow third-party extensions to be integrated into ISA.

Syntax

[ collFPCVendorParametersSets = ] FPCDestinationSets.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCDestinationSets


FPCDialupEntry Object

The FPCDialupEntry object represents a dialup entry that you can use to develop routing rules.

Note to C++ Programmers

This object implements the IFPCDialupEntry interface.

Methods

The following table lists the methods of the FPCDialupEntry object.

Method | Description
Refresh | Restores all original values to the FPCDialupEntry object.
Save | Saves all changes to persistent storage.

Properties

The following table lists the properties of the FPCDialupEntry object.

Property | Description
AuthenticationEnabled | Sets or retrieves whether the use of authentication is enabled.
Credentials | Retrieves an FPCCredentials object to read and write credential information.
Description | Sets or retrieves the description of the dialup entry..
Name | Sets or retrieves the name of the dialup entry.
RasPhoneBookEntry | Sets or retrieves the RasPhoneBookEntry property.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCDialupEntry object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDialupEntry.AuthenticationEnabled Property

Sets or retrieves whether the use of authentication in upstream routing is enabled.

Syntax

FPCDialupEntry.AuthenticationEnabled [= bEnabled ]

Possible Values

bEnabled
Boolean value that has either of two settings:
Setting | Meaning
TRUE | Authentication is enabled.
FALSE | Authentication is disabled.

The property is read-write.

Applies To

FPCDialupEntry


FPCDialupEntry.Credentials Property

Retrieves an FPCCredentials object to read and write credential information.

Syntax

[ oFPCCredentials = ] FPCDialupEntry.Credentials

Possible Values

oFPCCredentials
Reference to an FPCCredentials object.

The property is read-only.

Applies To

FPCDialupEntry


FPCDialupEntry.Description Property

Sets or retrieves the description of the dialup entry. The description is stored as a string.

Syntax

FPCDialupEntry.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the domain array.

The property is read-write.

Applies To

FPCDialupEntry


FPCDialupEntry.Name Property

Sets or returns the name of the dialup entry object.

Syntax

FPCDialupEntry.Name [ = sName ]

Possible Values

sName
String that specifies the name of the alert object.

The property is read-write.

Applies To

FPCDialupEntry


FPCDialupEntry.RasPhoneBookEntry Property

Sets or returns a Remote Access Service (RAS) phone book entry.

Syntax

FPCDialupEntry.RasPhoneBookEntryAuthenticationEnabled [= sEntry ]

Possible Values

sEntry
String that specifies the name of the RAS phone book entry.

The property is read-only.

Applies To

FPCDialupEntry


FPCDialupEntry.Refresh Method

Reads the object information from persistent storage, discarding any changes to the current object that were not saved.

Syntax

FPCDialupEntry.Refresh()

Applies To

FPCDialupEntry


FPCDialupEntry.Save Method

Saves the object to persistent storage.

Syntax

FPCDiDialupEntry.Save()

Applies To

FPCDialupEntry


FPCDialupEntry.VendorParametersSets Property

Returns a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection will be backed up from the Active Directory with all other ISA objects.

Syntax

[ collFPCVendorParametersSets = ] FPCDialupEntry.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCDialupEntry


FPCDialupEntries Collection

The FPCDialupEntries collection provides access to a group of FPCDialupEntry objects.

Note to C++ Programmers

This object implements the IFPCDialupEntries interface.

Methods

The following table lists the methods of the FPCDialupEntries collection.

Method | Description
Item | Retrieves the given FPCDialupEntry object from the collection.
Refresh | Restores all original values to the FPCDialupEntries collection.
Remove | Removes an object from the collection
Save | Saves all changes to persistent storage

Properties

The following table lists the properties of the FPCDialupEntries collection.

Property | Description
Count | Retrieves the number of objects in the collection

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDialupEntries.Count Property

Retrieves the number of FPCDialupEntry objects in the collection.

Syntax

[ lCount = ] FPCDialupEntries.Count

Possible Values

lCount
Long value that specifies the number of dialup entry objects.

The property is read-only.

Applies To

FPCDialupEntries


FPCDialupEntries.Item Method

Retrieves the given FPCDialupEntry object from the collection.

Syntax

[ vItem = ] FPCDialupEntries.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCDialupEntry. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCDialupEntries


FPCDialupEntries.Refresh Method

Reads all the FPCDialupEntry objects from persistent storage, discarding any changes that were not saved.

Syntax

FPCDialupEntries.Refresh()

Applies To

FPCDialupEntries


FPCDialupEntries.Remove Method

Removes an FPCDialupEntry object from the collection.

Syntax

FPCDialupEntries.Remove( vItem )

Parameters

vItem
Required. Name or one-based index of the object to remove.

Applies To

FPCDialupEntries


FPCDialupEntries.Save Method

Saves all the FPCDialupEntry objects in the collection to persistent storage.

Syntax

FPCDialupEntries.Save()

Applies To

FPCDialupEntries


FPCDirectAddressDestination Object

The FPCDirectAddressDestination object represents a single direct address destination in the client configuration of the ISA domain array. You can define addresses that the client will access directly rather than through the ISA Server. To see this functionalilty in the ISA Server administration tool, right-click on Web Browser in the Client Configuration pane to view the Web Browser Properties dialog box, and select the Direct Access tab.

This object is a member of the FPCDirectAddressDestinations collection.

Note to C++ Programmers

This collection implements the IFPCDirectAddressDestination interface.

Methods

The following table lists the methods of the FPCDirectAddressDestination object.

Method | Description
Refresh | Reads the IP address range information from persistent storage, discarding any changes to the current object that were not saved.
Save | Saves the IP address range to persistent storage.

Properties

The following table lists the properties of the FPCDirectAddressDestination object.

Property | Description
DomainName | Sets or retrieves the domain name.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDirectAddressDestination.DomainName Property

Sets or retrieves the domain name.

Syntax

FPCDirectAddressDestination.DomainName [ = sDomain ]

Possible Values

sDomain
String that specifies the domain name.

The property is read-write.

Applies To

FPCDirectAddressDestination


FPCDirectAddressDestination.Refresh Method

Reads the object information from persistent storage, discarding any changes to the current object that were not saved.

Syntax

FPCDirectAddressDestination.Refresh()

Applies To

FPCDirectAddressDestination


FPCDirectAddressDestination.Save Method

Saves the object to persistent storage.

Syntax

FPCDirectAddressDestination.Save()

Applies To

FPCDirectAddressDestination


FPCDirectAddressDestinations Collection

The FPCDirectAddressDestinations collection provides access to a group of FPCDirectAddressDestination objects. Clients access each destination in this collection directly; that is, they bypass the Firewall service. It is a property of the FPCClientAutoScript object.

Note to C++ Programmers

This collection implements the IFPCDirectAddressDestinations interface.

Methods

The following table lists the methods of the FPCDirectAddressDestinations collection.

Method | Description
AddDomainSuffix | Adds a domain suffix.
Item | Retrieves the given FPCDirectAddressDestination object from the collection.
Refresh | Reads all the FPCDirectAddressDestination objects from persistent storage, discarding any changes that were not saved.
Remove | Removes an FPCDirectAddressDestination object from the collection.
Save | Saves all the FPCDirectAddressDestination objects in the collection to persistent storage.

Properties

The following table lists the properties of the FPCDirectAddressDestinations collection.

Property | Description
Count | Retrieves the number of destination objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDirectAddressDestinations.AddDomainSuffix Method

Adds a domain suffix and returns a reference to an FPCDirectAddressDestination object. You can indicate a group of addresses that the client can access directly, rather than through the ISA Server, by specifying a domain suffix for which direct access is allowed. To see this functionality In the ISA Server administration tool, right click on Web Browser in the Client Configuration pane to view the Web Browser Properties dialog box. On the Direct Access tab, click Add.

Syntax

[ oFPCDirectAddressDestination = ] FPCDirectAddressDestinations.AddDomainSuffix( sDomain )

Parameter

sDomain
String value that specifies the domain.

Return Value

oFPCDirectAddressDestination
Returns a reference to an FPCDirectAddressDestination object.

Applies To

FPCDirectAddressDestinations


FPCDirectAddressDestinations.Count Property

Retrieves the number of FPCDirectAddressDestination objects in the collection.

Syntax

[ lCount = ] FPCDirectAddressDestinations.Count

Possible Values

lCount
Long value that specifies the number of direct destination objects.

The property is read-only.

Applies To

FPCDirectAddressDestinations


FPCDirectAddressDestinations.Item Method

Retrieves the given FPCDirectAddressDestination object from the collection.

Syntax

[ vItem = ] FPCDirectAddressDestinations.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCDirectAddressDestination. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCDirectAddressDestinations


FPCDirectAddressDestinations.Refresh Method

Reads all the FPCDirectAddressDestination objects from persistent storage, discarding any changes that were not saved.

Syntax

FPCDirectAddressDestinations.Refresh()

Applies To

FPCDirectAddressDestinations


FPCDirectAddressDestinations.Remove Method

Removes an FPCDirectAddressDestination object from the collection.

Syntax

FPCDirectAddressDestinations.Remove( vItem )

Parameters

vItem
Required. Name or one-based index of the object to remove.

Applies To

FPCDirectAddressDestinations


FPCDirectAddressDestinations.Save Method

Saves all the FPCDirectAddressDestination objects in the collection to persistent storage.

Syntax

FPCDirectAddressDestinations.Save()

Applies To

FPCDirectAddressDestinations


FPCDirectIpDestination Object

The FPCDirectIpDestination object represents a range of IP destinations in the client configuration of an ISA array. You can indicate an address or group of addresses that the client can access directly, rather than through the ISA Server, by specifying an IP address or range of IP addresses for which direct access is allowed. To see this functionality In the ISA Server administration tool, right click on Web Browser in the Client Configuration pane to view the Web Browser Properties dialog box. On the Direct Access tab, click Add.

The range can consists of a single IP address, if you give FPCDirectIpDestination.IP_From the same value as FPCDirectIpDestination.IP_To.

Note to C++ Programmers

This collection implements the IFPCDirectIpDestination interface.

Methods

The following table lists the methods of the FPCDirectIpDestination object.

Method | Description
Refresh | Reads the IP address range information from persistent storage, discarding any changes to the current object that were not saved.
Save | Saves the IP address range to persistent storage.

Properties

The following table lists the properties of the FPCDirectIpDestination object.

Property | Description
IP_From | Sets or retrieves the base IP address of the range.
IP_To | Sets or retrieves the end of the IP range of the range.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDirectIpDestination.IP_From Property

Sets or retrieves the lower-bound IP address of the range. This IP address cannot be greater that that provided in the FPCDirectIpDestination.IP_To property. It can be equal to the IP address in FPCDirectIpDestination.IP_To, resulting in a range consisting of a single address.

Syntax

FPCDirectIpDestination.Ip_From( sIp )

Possible Values

sIp
String that specifies the lower-bound IP address of the range.

The property is read-write.

Applies To

FPCDirectIpDestination


FPCDirectIpDestination.IP_To Property

Sets or retrieves the upper bound of the IP range.

Syntax

FPCDirectIpDestination.Ip_To()

Possible Values

sIp
String that specifies the upper-bound IP address of the range.

The property is read-write.

Applies To

FPCDirectIpDestination


FPCDirectIpDestination.Refresh Method

Reads the object information from persistent storage, discarding any changes to the current object that were not saved.

Syntax

FPCDirectIpDestination.Refresh()

Applies To

FPCDirectIpDestination


FPCDirectIpDestination.Save Method

Saves the object to persistent storage, discarding any changes to the current object that were not saved.

Syntax

FPCDirectIpDestination.Save()

Applies To

FPCDirectIpDestination


FPCDirectIpDestinations Collection

The FPCDirectIpDestinations collection of Internet Protocol (IP) destinations for which clients will bypass the . You can use this object to access the collection of FPCDirectIpDestination objects. It is a property of the FPCClientAutoScript object.

Note to C++ Programmers

This collection implements the IFPCDirectIpDestinations interface.

Methods

The following table lists the methods of the FPCDirectIpDestinations collection.

Method | Description
AddIp | Adds a range of IP addresses to the collection.
Item | Retrieves a given FPCDirectIpDestination object from the collection.
Refresh | Reads all the FPCDirectIpDestination objects from persistent storage, discarding any changes that were not saved.
Remove | Removes an FPCDirectIpDestination object from the collection.
Save | Saves all the FPCDirectIpDestination objects in the collection to persistent storage.

Properties

The following table lists the properties of the FPCDirectIpDestinations collection.

Property | Description
Count | Retrieves the number of destination objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDirectIpDestinations.AddIp Method

Adds a range of IP addresses to the collection.

Syntax

[ oFPCDirectIpDestinations ] FPCDirectIpDestinations.AddIp( sIP_From, sIP_To )

Parameters

sIP_From
String that specifies the base IP address of the range.
sIP_To
String that specifies the end of the IP range.

Return Values

oFPCDirectIpDestinations
Returns a reference to an FPCDirectIpDestination object.

Applies To

FPCDirectIpDestinations


FPCDirectIpDestinations.Count Property

Retrieves the number of FPCDirectIpDestination objects in the collection.

Syntax

[ lCount = ] FPCDirectIpDestinations.Count

Possible Values

lCount
Long value that specifies the number of destination objects.

The property is read-only.

Applies To

FPCDirectIpDestinations


FPCDirectIpDestinations.Item Method

Retrieves the given FPCDirectIpDestination object from the collection.

Syntax

[ vItem = ] FPCDirectIpDestinations.Item( IP_FromOrIndex, IP_To )

Parameters

IP_FromOrIndex
One-based index of the object to retrieve, or domain name or lower-bound IP.
sIp_To
Optional. String that specifies the higher-bound IP of the object to retrieve; needed if providing a lower-bound IP in IP_FromOrIndex.

Return Value

vItem
If successful, returns a reference to an object of type FPCDirectIpDestination. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCDirectIpDestinations


FPCDirectIpDestinations.Refresh Method

Reads the object information from persistent storage, discarding any changes to the current object that were not saved.

Syntax

FPCDirectIpDestinations.Refresh()

Applies To

FPCDirectIpDestinations


FPCDirectIPDestinations.Remove Method

Removes a FPCDirectIpDestination object from the collection.

Syntax

FPCDirectIpDestinations.Remove( vItem )

Parameters

vIpOrIndex
Required. One-based index or lower-bound IP address of the destination(s) to remove.
vIpto
Optional. Upper-bound IP address of the destinations to remove. Necessary if vIpOrIndex provides a lower-bound IP address.

Applies To

FPCDirectIpDestinations


FPCDirectIPDestinations.Save Method

Saves the object to persistent storage, discarding any changes to the current object that were not saved.

Syntax

FPCDirectIpDestinations.Save()

Applies To

FPCDirectIpDestinations


FPCDiskDrive Object

The FPCDiskDrive object represents a single disk drive of an ISA Server computer. This object lets you read the drive's properties.

This object is a member of the FPCDiskDrives collection.

Note to C++ Programmers

This object implements the IFPCDiskDrive interface.

Properties

The following table lists the properties of the FPCDiskDrive object.

Property | Description
DiskSizeInMegs | Retrieves the size of the disk.
FileSystem | Retrieves the name of the file system.
FreeSpaceInMegs | Retrieves the size of the free space, in megs, on the current disk.
Name | Retrieves the name of the drive.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDiskDrive.DiskSizeInMegs Property

Retrieves the size of the disk in megabytes.

Syntax

[ iSize = ] FPCDiskDrive.DiskSizeInMegs

Possible Values

iSize
Integer that specifies the size, in megabytes, of the disk.

The property is read-only.

Applies To

FPCDiskDrive


FPCDiskDrive.FileSystem Property

Retrieves the name of the file system.

Syntax

[ sName = ] FPCDiskDrive.FileSystem

Possible Values

sName
String that specifies the name of the file system. For example, "FAT", "FAT32", or "NTFS".

The property is read-only.

Applies To

FPCDiskDrive


FPCDiskDrive.FreeSpaceInMegs Property

Retrieves the size of the free space, in megabytes, on the current disk.

Syntax

[ iSize = ] FPCDiskDrive.FreeSpaceInMegs

Possible Values

iSize
Integer that specifies the size, in megabytes, of the free space on the current disk.

The property is read-only.

Applies To

FPCDiskDrive


FPCDiskDrive.Name Property

Returns the name of the drive; for example, "C" or "D". The drive name returned cannot be changed with this property.

Syntax

[ sName = ] FPCDiskDrive.Name

Possible Values

sName
String that specifies the name of the drive.

The property is read-only.

Applies To

FPCDiskDrive


FPCDiskDrives Collection

The FPCDiskDrives collection provides access to a group of FPCDiskDrive objects. This object is a property of an FPCServer object.

Note to C++ Programmers

This collection implements the IFPCDiskDrives interface.

Methods

The following table lists the methods of the FPCDiskDrives collection.

Method | Description
Item | Retrieves the given FPCDiskDrive object from the collection.
Refresh | Reads all the FPCDiskDrive objects from persistent storage, discarding any changes to the objects that were not saved.

Properties

The following table lists the properties of the FPCDiskDrives collection.

Property | Description
Count | Retrieves the number of disk drive objects in the collection.
TotalDiskSizeInMegs | Retrieves the total amount of disk space in all NTFS file system drives.
TotalFreeSizeInMegs | Retrieves the total amount of free space in all NTFS file system drives.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCDiskDrives collection storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDiskDrives.Count Property

Retrieves the number of FPCDiskDrive objects in the collection.

Syntax

[ iCount = ] FPCDiskDrives.Count

Possible Values

iCount
Integer that specifies the number of FPCDiskDrive objects.

The property is read-only.

Applies To

FPCDiskDrives


FPCDiskDrives.Item Method

Retrieves the given FPCDiskDrive object from the collection.

Syntax

[ vItem = ] FPCDiskDrives.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCDiskDrive. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCDiskDrives


FPCDiskDrives.Refresh Method

Reads all the FPCDiskDrive objects from persistent storage, discarding any changes to objects that were not saved.

Syntax

FPCDiskDrives.Refresh()

Applies To

FPCDiskDrives


FPCDiskDrives.TotalDiskSizeInMegs Property

Retrieves the total amount of disk space in all NTFS file system drives.

Syntax

[ iSize = ] FPCDiskDrives.TotalDiskSizeInMegs

Possible Values

iSize
Integer value that specifies the total size, in megabytes, of free space in all NTFS file system drives.

The property is read-only.

Applies To

FPCDiskDrives

See Also

FPCDiskDrive


FPCDiskDrives.TotalFreeSizeInMegs Property

Retrieves the total amount of free space in all NTFS file system drives.

Syntax

[ iSize = ] FPCDiskDrives.TotalFreeSizeInMegs

Possible Values

iSize
Integer value that specifies the total size, in megabytes, of free space in all NTFS file system drives.

The property is read-only.

Applies To

FPCDiskDrives

See Also

FPCDiskDrive


FPCDiskDrives.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCDiskDrives collection's storage. The VendorParametersSets property is designed to allow third-party extensions to be integrated into ISA.

Syntax

[ collFPCVendorParametersSets = ] FPCDiskDrives.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCDiskDrives


FPCEnterprise Object

The FPCEnterprise object provides access to the enterprise policy interfaces. The enterprise policy includes site and content rules and protocol rules. The enterprise policy can be applied to any domain array, and can be augmented by the domain array's own policy. This allows administrators at branch and departmental levels to adopt governing enterprise policies.

The FPCEnterprise object is a property of the FPC root object.

Note to C++ Programmers

This object implements the IFPCEnterprise interface.

Methods

The following table lists the methods of the FPCEnterprise object.

Method | Description
Backup | Backs up the all enterprise configuration to a file.
GetSecurityDescriptor | Gets the security descriptor.
Refresh | Refreshes all the properties of the object, returning them to the values they held when the object was first created.
Restore | Restores all original values to the FPCEnterprise object.
Save | Saves the current object values. This method must be called to save any changes to persistent storage.
SetPolicy | Sets the values of the PolicyUsedFlag and the DefaultPolicy properties.
SetSecurityDescriptor | Sets the security descriptor.

Properties

The following table lists the properties of the FPCEnterprise object.

Property | Description
AllowPublishing | Sets or returns a Boolean value that specifies the default value for any domain array that is not in the FPCArrayPolicyConfigs collection.
ArrayPolicyConfigs | Returns an object holding a collection that maps each domain array to a global policy.
BackupComment | Reads the backup comment from a file.
DefaultPolicy | Returns the name of the default global policy, or NULL for using the first policy in the FPCEnterprisePolicies collection.
Extensions | Returns an FPCExtensions object.
ForcePacketFiltering | Prevents an administrator from disabling IP packet filtering.
Policies | Returns an object holding all global policies.
PolicyElements | Returns an object holding all global policy configuration.
PolicyUsedFlag | Returns a value that specifies the default value for any domain array that is not in the FPCArrayPolicyConfigs collection.
VendorParametersSets | Programmatically accesses vendor-specific data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCEnterprise.AllowPublishing Property

Sets or returns a Boolean value that specifies the default value for any domain array that is not in the FPCArrayPolicyConfigs collection.

Syntax

FPCEnterprise.AllowPublishing [ = bAllow ]

Return Values

bAllow
A Boolean value that specifies the default value to allow publishing in the current domain array.

This property is read-write.

Applies to

FPCEnterprise


FPCEnterprise.ArrayPolicyConfigs Property

Returns a collection of all domain arrays and the corresponding policy.

Syntax

[ collFPCArrayPolicyConfigs = ] FPCEnterprise.ArrayPolicyConfigs

Possible Values

collFPCArrayPolicyConfigs
Reference to an FPCArrayPolicyConfigs collection.

This property is read-only.

Applies To

FPCEnterprise

See Also

FPCArrayPolicyConfig


FPCEnterprise.Backup Method

Backs up the all enterprise policy configuration to a file.

Syntax

FPCEnterprise.Backup ( sFileName, sComment, bOverwrite, bValidate )

Parameters

sFileName
A string value that specifies the name of the file that will contain a copy of the information after the operation is complete.
sComment
Optional. A string value that specifies a comment that can be added to the backup file.
bOverwrite
Optional. A Boolean value that specifies whether to allow the operation to continue when a backup file with the same name already exists.
bValidate
Optional. A Boolean value that specifies whether to validate the consistency of the backup file after the completion of the backup operation. Currently not supported.

Applies to

FPCEnterprise


FPCEnterprise.BackupComment Property

Reads the backup comment from a file.

Syntax

[ sBackupComment = ] FPCEnterprise.BackupComment ( sFileName )

Parameters

sFileName
A string value that specifies the name of the file that contains a backup of the enterprise information.

Return Values

sBackupComment
A string value that specifies a comment that was added to the backup file when it was created.

Applies to

FPCEnterprise


FPCEnterprise.DefaultPolicy Property

Returns the name of the default global policy, or NULL for using the first policy in the FPCEnterprisePolicies collection. This policy is used for any domain array that is not in the FPCArrayPolicyConfigs collection.

Syntax

[ sPolicyName = ] FPCEnterprise.PolicyName

Possible Values

sPolicyName
String value that specifies the name of the default policy.

The property is read only.

Applies To

FPCEnterprise


FPCEnterprise.Extensions Property

Returns an FPCExtensions object.

Syntax

[ oFPCExtensions = ] FPCEnterprise.Extensions

Possible Values

oFPCExtensions
Reference to an FPCExtensions object.

Applies to

FPCEnterprise


FPCEnterprise.ForcePacketFiltering Property

Prevents an administrator from disabling IP packet filtering. This property is the default value for domain arrays in the FPCArrayPolicyConfigs collection.

FPCEnterprise.ForcePacketFiltering [ = bForce ]

Return Values

bForce
Boolean value that specifies the default value for force IP packet filtering in a domain array.

The property is read-write.

Applies To

FPCEnterprise


FPCEnterprise.GetSecurityDescriptor Method

Returns an FPCSecurityDescriptor object that represents security settings.

Syntax

[ oFPCSecurityDescriptor = ] FPCEnterprise.GetSecurityDescriptor( lSecurityInfo )

Parameters

lSecurityInfo
Long value that specifies security information.

Return Value

oFPCSecurityDescriptor
Reference to an FPCSecurityDescriptor object.

Remarks

This method uses related Windows functionality. For more information, see GetSecurityInfo in MSDN.

Applies to

FPCEnterprise


FPCEnterprise.Policies Property

Returns a collection of all global policies.

Syntax

[ collFPCEnterprisePolicies = ] FPCEnterprise.Policies

Possible Values

collFPCEnterprisePolicies
Reference to an FPCEnterprisePolicies collection.

This property is read-only.

Applies To

FPCEnterprise

See Also

FPCEnterprisePolicy


FPCEnterprise.PolicyElements Property

Returns an object holding all global policy configuration. The FPCPolicyElements object itself has many properties that are important to ISA configuration, such as all scheduling information, destination sets, client address sets, protocol definitions, all filtering information, and all bandwidth class information. You can access all these configuration areas programmatically.

Syntax

[ oFPCPolicyElements = ] FPCEnterprise.PolicyElements

Possible Values

oFPCPolicyElements
Reference to an FPCPolicyElements object.

This property is read-only.

Applies To

FPCEnterprise


FPCEnterprise.PolicyUsedFlag Property

Returns a value that specifies the default value for any domain array that is not in the FPCArrayPolicyConfigs collection.

Syntax

[ PolicyUsed = ] FPCEnterprise.PolicyUsedFlag

Possible Values

PolicyUsed
Specifies the default value for allowing local policy. It can have a value from the FpcPolicyUsed enumerated type.

The property is read-only.

Applies To

FPCEnterprise


FPCEnterprise.Refresh Method

Restores all original values to the FPCEnterprise object. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

Syntax

FPCEnterprise.Refresh()

Applies To

FPCEnterprise


FPCEnterprise.Restore Method

Restores the enterprise configuration from a file.

Syntax

FPCEnterprise.Restore ( sFileName, bValidate )

Parameters

sFileName
A string value that specifies the name of the file that contains the enterprise configuration.
bValidate
Optional. A Boolean value that specifies whether to validate the consistency of the configuration in the backup file. Currently not supported.

Applies to

FPCEnterprise


FPCEnterprise.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made will not be saved until after the Save method is called.

Syntax

FPCEnterprise.Save()

Applies To

FPCEnterprise


FPCEnterprise.SetPolicy Method

Sets the values of the PolicyUsedFlag and the DefaultPolicy properties.

Syntax

FPCEnterprise.SetDefaults( PolicyUsed, sDefaultPolicy )

Parameters

PolicyUsed
A value from the FpcPolicyUsed enumerated type that specifies whether the domain array uses its local and/or enterprise policy.
sDefaultPolicy
String that specifies the name of the default policy. It can be empty if the enterprise policy is not being used.

Applies To

FPCEnterprise


FPCEnterprise.SetSecurityDescriptor Method

Sets the values of the FPCSecurityDescriptor object that represents security settings.

Syntax

FPCEnterprise.SetSecurityDescriptor( lSecurityInfo, oFPCSecurityDescriptor )

Parameters

lSecurityInfo
Long value specifying security information.
oFPCSecurityDescriptor
Reference to a FPCSecurityDescriptor object.

Remarks

This method uses related Windows functionality. For more information, see SetSecurityInfo in MSDN.

Applies to

FPCEnterprise

Built on Tuesday, May 23, 2000


FPCEnterprise.VendorParametersSets Property

Returns a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection will be backed up from the Active Directory with all other ISA objects.

Syntax

[ oFPCVendorParametersSets = ] FPCEnterprise.VendorParametersSets

Possible Values

oFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCEnterprise


FPCEnterprisePolicy Object

The FPCEnterprisePolicy object defines a single ISA policy. A policy is a combination of rules and IP packet filters that you define, and that can be applied on the domain array level or enterprise level. Each ISA policy contains configurable properties.

This object is a member of the FPCEnterprisePolicies collection.

Note to C++ Programmers

This object implements the IFPCEnterprisePolicy interface.

Methods

The following table lists the methods of the FPCEnterprisePolicy object.

Method | Description
GetSecurityDescriptor | Returns an FPCSecurityDescriptor object that represents security settings of this policy.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.
Save | Saves the object's configuration information to persistent storage.
SetSecurityDescriptor | Sets the values of the FPCSecurityDescriptor object that represents security settings of this policy.

Properties

The following table lists the properties of the FPCEnterprisePolicy object.

Property | Description
CreatedTime | Returns a DATE data type that specifies the creation time of the object.
Description | Sets or returns the description of the policy in the form of a string.
LastModifiedTime | Returns a DATE that specifies the last modification time of the object.
Name | Sets or returns the name of the policy.
ProtocolRules | Retrieves a collection of the protocol rules.
SiteAndContentRules | Retrieves a collection of all site and content rules.
VendorParametersSets | Retrieves a reference to an object used to access a vendor's data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCEnterprisePolicy.CreatedTime Property

Returns a DATE data type that specifies the creation time of the object.

Syntax

[ dCreatedTime = ] FPCEnterprisePolicy.CreatedTime

Possible Values

dCreatedTime
Reference to the DATE data type.

The property is read-only.

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.Description Property

Sets or retrieves the description of the policy. The description is stored as a string.

Syntax

FPCEnterprisePolicy.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the domain array.

The property is read-write.

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.GetSecurityDescriptor Method

Returns an FPCSecurityDescriptor object that represents security settings of this policy.

Syntax

[ oFPCSecurityDescriptor = ] FPCEnterprisePolicy.GetSecurityDescriptor( lSecurityInfo )

Parameters

lSecurityInfo
Long value specifying security information.

Return Value

oFPCSecurityDescriptor
Reference to an FPCSecurityDescriptor object.

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.LastModifiedTime Property

Returns DATE data type that specifies the last modification time of the object.

Syntax

[ dLastModifiedTime = ] FPCEnterprisePolicy.LastModifiedTime

Possible Values

dLastModifiedTime
Reference to the DATE data type.

The property is read-only.

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.Name Property

Sets or retrieves the name of the policy. The name of the policy is stored as a string.

Syntax

FPCEnterprisePolicy.Name [ = sName ]

Possible Values

sName
String that specifies the domain array name.

The property is read-write.

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.ProtocolRules Property

Retrieves a collection of the protocol rules in this policy.

Syntax

[ collFPCProtocolRules = ] FPCEnterprisePolicy.ProtocolRules

Possible Values

collFPCProtocolRules
Reference to the FPCProtocolRules collection.

Applies To

FPCEnterprisePolicy

See Also

FPCProtocolRule


FPCEnterprisePolicy.Refresh Method

Reads the object from persistent storage, discarding any changes to the object that were not saved.

Syntax

FPCEnterprisePolicy.Refresh()

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.Save Method

Saves the object's configuration to persistent storage.

Syntax

FPCEnterprisePolicy.Save()

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.SetSecurityDescriptor Method

Sets the values of the FPCSecurityDescriptor object that represents security settings of this policy.

Syntax

FPCEnterprisePolicy.SetSecurityDescriptor( lSecurityInfo, oFPCSecurityDescriptor )

Parameters

lSecurityInfo
Long value that specifies security information.
oFPCSecurityDescriptor
Reference to a FPCSecurityDescriptor object.

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.SiteAndContentRules Property

Retrieves a collection of all site and content rules in this policy.

Syntax

[ collFPCSiteAndContentRules = ] FPCEnterprisePolicy.SiteAndContentRules

Possible Values

collFPCSiteAndContentRules
Reference to the FPCSiteAndContentRules collection.

Applies To

FPCEnterprisePolicy

See Also

FPCSiteAndContentRule


FPCEnterprisePolicy.VendorParametersSets Property

Returns a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection will be backed up from the Active Directory with all other ISA objects.

Syntax

[ collFPCVendorParametersSets = ] FPCEnterprisePolicy.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicies Collection

The FPCEnterprisePolicies collection provides access to a collection of FPCEnterprisePolicy objects.

FPCEnterprisePolicies is a property of the FPCEnterprisePolicy object.

Note to C++ Programmers

This collection implements the IFPCEnterprisePolicies interface.

Methods

The following table lists the methods of the FPCEnterprisePolicies collection.

Method | Description
Add | The Add method of the FPCEnterprisePolicies collection adds a new policy to the collection.
Item | Returns the policy object specified by the integer parameter of this method.
Refresh | Refreshes all the properties of the object, returning them to the values they held when the object was first created.
Remove | Removes the policy object from the collection.
Save | Saves the current object values. This method must be called to save any changes to persistent storage.

Properties

The following table lists the properties of the FPCEnterprisePolicies collection.

Property | Description
Count | Returns the number of policy objects in the collection.
VendorParametersSets | The VendorParametersSets property is used to programmatically access vendor-specific data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCEnterprisePolicies.Add Method

Adds a new policy to the collection and returns a reference to it.

Syntax

[ oFPCEnterprisePolicy = ] FPCEnterprisePolicies.Add( sName, sPolicyToClone )

Parameters

sName
Required. String that specifies the name of FPCEnterprisePolicy object to add.
sPolicyToClone
Optional. String that specifies the policy name to which to copy the configuration.

Return Value

oFPCEnterprisePolicy
Returns a reference to the new FPCEnterprisePolicy object.

Applies To

FPCEnterprisePolicies


FPCEnterprisePolicies.Count Property

Returns the number of policy objects within the collection.

Syntax

[ iCount = ] FPCEnterprisePolicies.Count

Possible Values

iCount
Integer value that specifies the number of FPCEnterprisePolicy objects.

The property is read-only.

Applies To

FPCEnterprisePolicies


FPCEnterprisePolicies.Item Method

Returns an FPCEnterprisePolicy object from the collection, specified by the required integer parameter.

Syntax

[ vItem = ] FPCEnterprisePolicies.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCEnterprisePolicy. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCEnterprisePolicies


FPCEnterprisePolicies.Refresh Method

Restores all original values to the collection. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

Syntax

FPCEnterprisePolicies.Refresh()

Applies To

FPCEnterprisePolicies


FPCEnterprisePolicies.Remove Method

Removes a policy from the collection.

Syntax

FPCEnterprisePolicies.Remove( iIndex )

Parameters

iIndex
Required. Name or one-based index of the FPCEnterprisePolicy object to remove.

Applies To

FPCEnterprisePolicies


FPCEnterprisePolicies.Save Method

Saves all configuration changes to persistent storage. Note that any changes made will not be saved until after the Save method is called.

Syntax

FPCEnterprisePolicies.Save()

Applies To

FPCEnterprisePolicies


FPCEnterprisePolicies.VendorParametersSets Property

Returns a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection will be backed up from the Active Directory with all other ISA objects.

Syntax

[ collFPCVendorParametersSets = ] FPCEnterprisePolicies.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCEnterprisePolicies


FPCEventDefinition Object

The FPCEvent Definition object is used to define a single event. Events describe conditions that require the attention of an administrator, and predetermined actions can be taken in response to particular events using the FPCAlert object. Each event is uniquely identified by its EventGUID property.

This object is a member of the FPCEventDefinitions collection.

For a more detailed programmatic example of using the FPCEventDefinitions collection, see Adding a Custom Event and Alert.

Note to C++ Programmers

This object implements the IFPCEventDefinition interface.

Methods

The following table lists the methods of the FPCEventDefinition object.

Method | Description
Refresh | Reads the object from persistent storage, discarding any changes to the object that were not saved.
Save | Saves the event's configuration to persistent storage.

Properties

The following table lists the properties of the FPCEventDefinition object.

Property | Description
AdditionalKeys | Returns the additional keys to this event.
AdditionalKeysCount | Returns the number of additional keys to this event.
Description | Sets or retrieves the description of the event.
EventGUID | Returns the GUID of the event.
EventsBeforeRaise | Sets or retrieves the default count of events that signals another event.
Event | Returns whether the event is installed by ISA.
MinEventsPerSecond | Sets or retrieves the default count of events per second that signals another event.
MinutesBeforeReRaise | Sets or retrieves the interval between invocations of the default count of minutes that signals another event.
Name | Sets or returns the name of the event.
VendorParametersSets | Returns a reference to an object for storing and loading custom data into the FPCEventDefinition object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCEventDefinition.AdditionalKeys Property

Returns the additional keys to this event.

Additional keys serve as a way to subdivide event objects into related subevents; for example, subdividing a disk-full event into log-disk-full or system-disk-full subevents. This allows for different alerts that are specific to subevents or one alert that is specific to all subevents.

Syntax

[ vKeys = ] FPCEventDefinition.Name

Possible Values

vKeys
Variant domain array that specifies the additional keys.

The property is read-only.

Applies To

FPCEventDefinition


FPCEventDefinition.AdditionalKeysCount Property

Returns the number of additional keys to this event.

Syntax

[ iCount = ] FPCEventDefinition.AdditionalKeysCount

Possible Values

iCount
Integer that specifies the number of additional keys.

The property is read-only.

Applies To

FPCEventDefinition


FPCEventDefinition.Description Property

Sets or retrieves the description of the event.

Syntax

FPCEventDefinition.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the event name.

The property is read-write.

Applies To

FPCEventDefinition


FPCEventDefinition.EventGUID Property

Returns the globally unique identifier (GUID) of the event.

Syntax

[ sGUID = ] FPCEventDefinition.EventGUID

Possible Values

sGUID
String that specifies the GUID of the event.

The property is read-only.

Applies To

FPCEventDefinition


FPCEventDefinition.EventsBeforeRaise Property

Sets or retrieves the default count of events that signals another event. This property serves only to display default values to users after they select this event. Only values set by the alert objects are used by the alert service.

The MinutesBeforeReRaise, EventsBeforeRaise, and MinEventsPerSecond properties of the FPCAlert object set the three thresholds that the alert service uses to signal alerts. For each alert, the alert service stores the last time the alert was signaled, a count of how many times the alert has been signaled per second and a count of the total number of times the alert has been signaled. An alert is given and the alert invokes the actions specific to the alert only when the three threshold requirements for signaling an alert are met simultaneously.

The EventsBeforeRaise property sets the threshold for the number of times the alert has been signaled.

Syntax

FPCEventDefinition.EventsBeforeRaise [ = iThreshold ]

Possible Values

iThreshold
Integer that specifies the threshold.

The property is read-write.

Applies To

FPCEventDefinition


FPCEventDefinition.Event Property

Returns whether the event is installed by ISA.

Note The events cannot be deleted.

Syntax

[ bAllow = ]FPCEventDefinition.Event

Possible Values

bAllow
A Boolean value that has either of these settings:
Setting | Meaning
TRUE | Event is installed by ISA.
FALSE | Event is installed by ISA Add-On.

The property is read-only.

Applies To

FPCEventDefinition


FPCEventDefinition.MinEventsPerSecond Property

Sets or retrieves the default count of events per second that signals another event. This property serves only to display default values to users after they select this event. Only values set by the alert objects are used by the alert service.

The MinutesBeforeReRaise, EventsBeforeRaise, and MinEventsPerSecond properties of the FPCAlert object set the three thresholds that the alert service uses to signal alerts. For each alert, the alert service stores the last time the alert was signaled, a count of how many times the alert has been signaled per second and a count of the total number of times the alert has been signaled. An alert is given and the alert invokes the actions specific to the alert only when the three threshold requirements for signaling an alert are met simultaneously.

The MinEventsPerSecond property sets the threshold for the number of alerts signaled per second.

Syntax

FPCEventDefinition.MinEventsPerSecond [ = iThreshold ]

Possible Values

iThreshold
Integer that specifies the threshold for the number of alerts signaled per second.

The property is read-write.

Applies To

FPCEventDefinition


FPCEventDefinition.MinutesBeforeReRaise Property

Sets or retrieves the interval between invocations of the default count of minutes that signals another event).

The MinutesBeforeReRaise, EventsBeforeRaise, and MinEventsPerSecond properties of the FPCAlert object set the three thresholds that the alert service uses to signal alerts. For each individual alert, the alert service stores the last time the alert was signaled, a count of how many times the alert has been signaled per second and a count of the total number of times the alert has been signaled. An alert is given and the alert invokes the actions specific to the alert only when the three threshold requirements for signaling an alert are met simultaneously.

The MinutesBeforeReRaise property sets the threshold for the last time the alert was signaled.

Syntax

FPCEventDefinition.MinutesBeforeReRaise [ = iInterval ]

Possible Values

iInterval
Integer that specifies the signaling interval.

The property is read-write.

Applies To

FPCEventDefinition


FPCEventDefinition.Name Property

Sets or retrieves the name of the event.

Syntax

FPCEventDefinition.Name [ = sName ]

Possible Values

sName
String that specifies the event name.

The property is read-write.

Applies To

FPCEventDefinition


FPCEventDefinition.Refresh Method

Reads the object from persistent storage, discarding any changes to the object that were not saved.

Syntax

FPCEventDefinition.Refresh()

Applies To

FPCEventDefinition


FPCEventDefinition.Save Method

Saves the event's configuration to persistent storage.

Syntax

FPCEventDefinition.Save()

Applies To

FPCEventDefinition


FPCEventDefinition.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCEventDefinition object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCEventDefinition.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCEventDefinition


FPCEventDefinitions Collection

FPCEventDefinitions gives access to a collection of FPCEventDefinition objects. Events describe conditions that require the attention of an administrator, and pre-determined actions can be taken in response to particular events using the FPCAlert object.

For a more detailed programmatic example of using the FPCEventDefinitions collection, see Adding a Custom Event and Alert.

This collection is a property of the FPCPolicyElements object.

Note to C++ Programmers

This collection implements the IFPCEventDefinitions interface.

Methods

The following table lists the methods of the FPCEventDefinitions collection.

Method | Description
Add | Creates a new event, inserts it into the collection, and returns a reference to it.
Item | Retrieves the given FPCEventDefinition object from the collection.
Refresh | Reads objects from persistent storage, discarding any changes to the objects that were not saved.
Remove | Removes an event definition from the collection.
Save | Saves the events' configuration to persistent storage.

Properties

The following table lists the properties of the FPCEventDefinitions collection.

Property | Description
Count | Retrieves the number of event-definition objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCEventDefinitions collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCEventDefinitions.Add Method

Creates a new event, inserts it into the collection, and returns a reference to it.

Syntax

[ oFPCEventDefinition = ] FPCEventDefinitionSet.Add( sName, sEventGUID, vAdditionalKeys )

Parameters

sName
Required. String that specifies the name of the new event. Name should be unique in the collection.
sEventGUID
Required. String that specifies the globally unique identifier (GUID) of the new event.
vAdditionalKeys
Optional. Reference to a string domain array of subevents. See FPCEventDefinition.AdditionalKeys.

Return Values

oFPCEventDefinition
Returns a reference to the FPCEventDefinition object of the new event.

Applies To

FPCEventDefinitions


FPCEventDefinitions.Count Property

Returns the number of event definition objects in the collection.

Syntax

[ iCount = ] FPCEventDefinitionSet.Count

Possible Values

iCount
Integer value that specifies the number of FPCEventDefinition objects.

The property is read-only.

Applies To

FPCEventDefinitions


FPCEventDefinitions.Item Method

Returns the given FPCEventDefinition object from the collection.

Syntax

[ vItem = ] FPCEventDefinitionSet.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCEventDefinition. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCEventDefinitions


FPCEventDefinitions.Refresh Method

Reads all the FPCEventDefinition objects from persistent storage, discarding any changes to the objects that were not saved.

Syntax

FPCEventDefinitionSet.Refresh()

Applies To

FPCEventDefinitions


FPCEventDefinitions.Remove Method

Removes an event definition from the collection.

Syntax

FPCEventDefinitionSet.Remove( iIndex )

Parameters

iIndex
Required. Name or one-based index of the FPCEventDefinition object to remove.

Applies To

FPCEventDefinitions


FPCEventDefinitions.Save Method

Saves the events' configuration to persistent storage.

Syntax

FPCEventDefinitionSet.Save()

Applies To

FPCEventDefinitions


FPCEventDefinitions.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCEventDefinitions collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCEventDefinitionSet.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCEventDefinitions


FPCExtensions Object

The FPCExtensions object is used to administer all configuration settings of ISA extensions.

Note to C++ Programmers

This collection implements the IFPCExtensions interface.

Methods

The following table lists the methods of the FPCExtensions object.

Method | Description
Refresh | Reads all the settings from persistent storage, discarding any changes that were not saved.
Save | Saves the current settings to persistent storage.

Properties

The following table lists the properties of the FPCExtensions object.

Property | Description
ApplicationFilters | Returns an lFPCApplicationFilters collection.
WebFilters | Returns an FPCWebFilters collection.
VendorParametersSets | Returns a reference to an object for storing and loading custom data into the object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCExtensions.ApplicationFilters Property

Returns an FPCApplicationFilters collection.

Syntax

[ collFPCApplicationFilters = ] FPCExtensions.ApplicationFilters

Possible Values

collFPCApplicationFilters
Reference to an FPCApplicationFilters collection.

The property is read-only.

Applies To

FPCExtensions


FPCExtensions.WebFilters Property

Returns an FPCWebFilters collection.

Syntax

[ collFPCWebFilters = ] FPCExtensions.WebFilters

Possible Values

collFPCWebFilters
Reference to an FPCWebFilters collection.

The property is read-only.

Applies To

FPCExtensions


FPCExtensions.Refresh Method

Reads all the settings from persistent storage, discarding any changes that were not saved.

Syntax

FPCExtensions.Refresh()

Applies To

FPCExtensions


FPCExtensions.Save Method

Saves the current settings to persistent storage.

Syntax

FPCExtensions.Save()

Applies To

FPCExtensions


FPCExtensions.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the object's storage..

Syntax

[ collFPCVendorParametersSets = ] FPCExtensions.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to an FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCExtensions


FPCFilterProtocol Object

The FPCFilterProtocol object is used to represent a single protocol registered by a application filter. An application filter can register a particular protocol so that it appears in the ISA administration tool. FPCFilterProtocol is a member of the FPCFilterProtocols collection.

Note to C++ Programmers

This object implements the IFPCFilterProtocol interface.

Methods

The following table lists the methods of the FPCFilterProtocol object.

Method | Description
Refresh | Reads the protocol's private data from persistent storage.
Save | Saves the protocol's private data to persistent storage.

Properties

The following table lists the properties of the FPCFilterProtocol object.

Property | Description
ApplicationFilterGuid | Retrieves the globaly unique identifier (GUID) that identifies the application filter. The vendor of the application filter provides the GUID.
Description | Sets or retrieves the description of the application filter protocol.
Guid | Retrieves the GUID that identifies the protocol.
Name | Retrieves the name of the application filter protocol.
PrimaryConnections | Retrieves a collection of all of this protocol's primary connections.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCFilterProtocol object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFilterProtocol.Description Property

Sets or retrieves the description of the application filter protocol.

Syntax

FPCFilterProtocol.Description [ = sDescription ]

Possible Values

sDescription
String specifying the description of the protocol.

The property is read-write.

Applies To

FPCFilterProtocol


FPCFilterProtocol.ApplicationFilterGuid Property

Retrieves the GUID that identifies the plug-in. The vendor of the plug-in provides the GUID.

Syntax

[ sGuid = ] FPCFilterProtocol.ApplicationFilterGuid

Possible Values

sGuid
String that specifies the GUID.

The property is read-only.

Applies To

FPCFilterProtocol


FPCFilterProtocol.Guid Property

Retrieves the globally unique identifier (GUID) that identifies the protocol.

Syntax

[ sGuid = ] FPCFilterProtocol.Guid

Possible Values

sGuid
String that specifies the GUID.

The property is read-only.

Applies To

FPCFilterProtocol


FPCFilterProtocol.Name Property

Retrieves the name of the application filter protocol.

Syntax

[ sName = ] FPCFilterProtocol.Name

Possible Values

sName
String that specifies the protocol name.

The property is read-only.

Applies To

FPCFilterProtocol


FPCFilterProtocol.PrimaryConnections Property

Retrieves a collection of all of this protocol's primary connections.

Syntax

[ collFPCProtocolConnections = ] FPCFilterProtocol.PrimaryConnections

Possible Values

collFPCProtocolConnections
Reference to an FPCProtocolConnections collection.

The property is read-only.

Remarks

A plug-in protocol must list its primary outbound connections in this list. The Firewall service uses the list to determine which NAT connections should be processed by the service.

Secondary connections should not be listed here.

Applies To

FPCFilterProtocol


FPCFilterProtocol.Refresh Method

Reads the protocol's private data from persistent storage.

Syntax

FPCFilterProtocol.Refresh()

Applies To

FPCFilterProtocol


FPCFilterProtocol.Save Method

Saves the protocol's private data to persistent storage.

Syntax

FPCFilterProtocol.Save()

Applies To

FPCFilterProtocol


FPCFilterProtocol.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCFilterProtocol object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCFilterProtocol.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCFilterProtocol


FPCFilterProtocols Collection

Represents all protocols that a single application filter supports. This object is used to access the collection of FPCFilterProtocol objects.

FPCFilterProtocols is a property of the FPCApplicationFilter object.

Note to C++ Programmers

This collection implements the IFPCFilterProtocols interface.

Methods

The following table lists the methods of the FPCFilterProtocols collection.

Method | Description
Add | Adds a new FPCFilterProtocol object to the collection.
Item | Retrieves the given Firewall service FPCFilterProtocol object from the collection.
Refresh | Reads all the application filter protocol objects from persistent storage, discarding any changes to the current object that were not saved.
Remove | Removes a plug-in protocol object from the collection.
Save | Saves the protocols' private data to persistent storage.

Properties

The following table lists the properties of the FPCFilterProtocols collection.

Property | Description
Count | Retrieves the number of application filter protocols in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading of custom data into the FPCFilterProtocol object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFilterProtocols.Add Method

Adds a new FPCFilterProtocol object to the collection.

Syntax

[ oFPCFilterProtocol = ] FPCFilterProtocols.Add( sGuid, sName )

Parameters

sGuid
Required. String that specifies the globally unique identifier (GUID) of the new plug-in.
sName
Required. String that specifies the name of the protocol.

Return Value

oFPCFilterProtocol
Reference to an FPCFilterProtocol object.

Applies To

FPCFilterProtocols


FPCFilterProtocols.Count Property

Retrieves the number of application filter protocols in the collection.

Syntax

[ iCount = ] FPCFilterProtocols.Count

Possible Values

iCount
Integer value specifying the number of plug-in protocols.

The property is read-only.

Applies To

FPCFilterProtocols

See Also

FPCFilterProtocol


FPCFilterProtocols.Item Method

Retrieves the given Firewall service FPCFilterProtocol object from the collection.

Syntax

[ vItem = ] FPCFilterProtocols.Item( vIndex )

Parameters

vIndex
Required. Globally unique identifier (GUID) or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCFilterProtocol. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCFilterProtocols


FPCFilterProtocols.Refresh Method

Reads all the FPCFilterProtocol objects from persistent storage, discarding any changes to the current object that were not saved.

Syntax

FPCFilterProtocols.Refresh()

Applies To

FPCFilterProtocols


FPCFilterProtocols.Remove Method

Removes an FPCFilterProtocol object from the collection.

Syntax

FPCFilterProtocols.Remove( vIndex )

Parameters

vIndex
Required. Globally unique identifier (GUID) or one-based index of the object to remove.

Applies To

FPCFilterProtocols


FPCFilterProtocols.Save Method

Saves the protocols' private data to persistent storage.

Syntax

FPCFilterProtocols.Save()

Applies To

FPCFilterProtocols


FPCFilterProtocols.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCFilterProtocols collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCFilterProtocols.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCFilterProtocols


FPCFirewallClientConfig Object

The FPCFirewallClientConfig object represents the configuration of the Firewall client of an ISA array. This object is a property of the FPCProxyClientConfig object.

Note to C++ Programmers

This object implements the IFPCFirewallClientConfig interface.

Methods

The following table lists the methods of the FPCFirewallClientConfig object.

Method | Description
Refresh | Reads the Firewall client information from persistent storage, discarding any changes to the current object that were not saved.
Save | Saves the Firewall client information to persistent storage.

Properties

The following table lists the properties of the FPCFirewallClientConfig object.

Property | Description
AccessType | Sets or retrieves the communication level that any Firewall client uses to contact the Firewall service.
ServerIp | Sets or retrieves whether the Firewall client accesses the ISA server using the server's IP address.
ServerOrArrayName | Sets or retrieves the name of the ISA server used by Firewall clients. This method assumes that the access type is fpcClientAccessSetByName value of the FpcFwAccessByType enumeration.
Settings | Retrieves the Firewall client configuration settings

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFirewallClientConfig.AccessType Property

Sets or retrieves the communication level that any Firewall client uses to contact the Firewall service.

Syntax

FPCFirewallClientConfig.AccessType [ = AccessType ]

Parameters

AccessType
Communication level. It can have a value from the FpcFwAccessByType enumeration.

Applies To

FPCFirewallClientConfig


FPCFirewallClientConfig.Refresh Method

Reads the Firewall client information from persistent storage, discarding any changes to the current object that were not saved.

Syntax

FPCFirewallClientConfig.Refresh()

Applies To

FPCFirewallClientConfig


FPCFirewallClientConfig.Save Method

Saves the Firewall client information to persistent storage.

Syntax

FPCFirewallClientConfig.Save()

Applies To

FPCFirewallClientConfig


FPCFirewallClientConfig.ServerIp Property

Sets or retrieves whether the Firewall client accesses the ISA server using the server's IP address.

Syntax

FPCFirewallClientConfig.ServerIp [ = sIP ]

Parameters

sIP
String that specifies if the client will use the IP address.

Applies To

FPCFirewallClientConfig


FPCFirewallClientConfig.ServerOrArrayName Property

Sets or retrieves the name of the ISA server used by Firewall clients. This method assumes that the access type is the value fpcClientAccessSetByName of the FpcFwAccessByType enumeration.

Syntax

FPCFirewallClientConfig.ServerOrArrayName [ = sName ]

Parameters

sName
String that specifies the name of the server.

Applies To

FPCFirewallClientConfig


FPCFirewallClientConfig.Settings Property

Retrieves the Firewall client settings in an FPCClientConfigSettings object.

Syntax

[ oFPCClientConfigSettings = ] FPCFirewallClientConfig.Settings

Parameters

oFPCClientConfigSettings
Reference to an FPCClientConfigSettings object.

Applies To

FPCFirewallClientConfig


FPCFirewallChaining Object

The FPCFirewallChaining object defines Firewall service chainings. You can use Firewall service chaining to configure the routing of Firewall service requests among the servers. When you use Firewall service chaining on a domain array, Firewall service requests are always routed to a specified server.

You can use the FPCFirewallChaining object to determine whether chaining is enabled, and to determine the name of the domain array to which to chain.

The FPCFirewallChaining object is a property of the FPCNetworkConfiguration object.

Note to C++ Programmers

This object implements the IFPCFirewallChaining interface.

Methods

The following table lists the methods of the FPCFirewallChaining object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.
Save | Saves the object's configuration information to persistent storage.

Properties

The following table lists the properties of the FPCFirewallChaining object.

Property | Description
AuthenticationEnabled | Sets or retrieves whether use of authentication in upstream routing is enabled.
ChainingAutoDialOut | Retrieves a reference to an object that represents the automatic-dial settings of the chaining connection.
Credentials | Retrieves an FPCCredentials object used to read and write credential information. This information will be used if a proxy server needs to authenticate when it chains to an upstream proxy server.
ForwardTo | Retrieves the name of the proxy or domain array to which to chain.
ForwardType | Sets or retrieves the mode of proxy forwarding.
PrimaryAutoDialOut | Retrieves a reference to an object that represents the automatic-dial settings of the primary connection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFirewallChaining.AuthenticationEnabled Property

Sets or retrieves whether use of authentication in upstream routing is enabled.

Syntax

FPCFirewallChaining.AuthenticationEnabled [= bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Authentication is enabled.
FALSE | Authentication is disabled.

The property is read-write.

Applies To

FPCFirewallChaining


FPCFirewallChaining.ChainingAutoDialOut Property

Retrieves a reference to an object that represents the automatic-dial settings of the chaining connection.

Syntax

[ oFPCAutoDial = ] FPCFirewallChaining.ChainingAutoDialOut

Possible Values

oFPCAutoDial
Reference to an FPCAutoDial object.

The property is read-only.

Applies To

FPCFirewallChaining


FPCFirewallChaining.Credentials Property

Retrieves an FPCCredentials object used to read and write credential information. A proxy server will use this information if it needs to authenticate when chaining to an upstream proxy server.

Syntax

[ oFPCCredentials = ] FPCFirewallChaining.Credentials

Possible Values

oFPCCredentials
Reference to an FPCCredentials object.

The property is read-only.

Applies To

FPCFirewallChaining


FPCFirewallChaining.ForwardTo Property

Retrieves the name of the proxy or domain array to which to chain.

Syntax

FPCFirewallChaining.ForwardTo [ = sName ]

Possible Values

sName
String that specifies the name of the proxy or domain array.

The property is read-write.

Applies To

FPCFirewallChaining


FPCFirewallChaining.ForwardType Property

Sets or retrieves the mode of proxy forwarding, either forwarding requests to the primary connection, or forwarding requests to another chaining proxy server.

Syntax

[ ForwardType = ] FPCFirewallChaining.ForwardType

Possible Values

ForwardType
Type of forwarding. It can have a value from the FpcFwForwardType enumerated type.

The property is read-write.

Applies To

FPCFirewallChaining


FPCFirewallChaining.PrimaryAutoDialOut Property

Retrieves a reference to an object that represents the automatic-dial settings of the primary connection.

Syntax

[ oAutoDial = ] FPCFirewallChaining.PrimaryAutoDialOut

Possible Values

oAutoDial
Reference to an FPCAutoDial object.

The property is read-only.

Applies To

FPCFirewallChaining


FPCFirewallChaining.Refresh Method

Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.

Syntax

FPCFirewallChaining.Refresh()

Applies To

FPCFirewallChaining


FPCFirewallChaining.Save Method

Saves the object's configuration to persistent storage.

Syntax

FPCFirewallChaining.Save()

Applies To

FPCFirewallChaining


FPCFirewallSession Object

The FPCFirewallSession object represents a single Windows Sockets (Winsock) session. A Winsock session is created each time a Firewall client makes a request. In the ISA administration tool, sessions are shown in the Real Time Monitoring node.

The FPCFirewallSession object is a member of the FPCFirewallSessions collection.

Note to C++ Programmers

This object implements the IFPCFirewallSession interface.

Methods

The following table lists the methods of the FPCFirewallSession object.

Method | Description
AbortSession | Stops all connections that have the user name and computer of the session, and removes the session from the collection.
Refresh | Reads the FPCFirewallSession objects by using a remote procedure call (RPC).

Properties

The following table lists the properties of the FPCFirewallSession object.

Property | Description
ClientMachine | Retrieves the client computer for this session.
UserName | Retrieves the user name for this session.
FirewallSessionConnections | Retrieves a pointer to the FPCFirewallSessionConnections collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFirewallSession.AbortSession Method

Stops all connections that have the user name and computer of the session.

Syntax

FPCWinsockSession.AbortSession()

Applies To

FPCFirewallSession


FPCFirewallSession.ClientMachine Property

Retrieves the address of the client computer.

Syntax

[ sClientMachine = ] FPCWinsockSession.ClientMachine

Possible Values

sClientMachine
String that specifies the client computer.

The property is read-only.

Applies To

FPCFirewallSession


FPCFirewallSession.Refresh Method

Reads all the properties of the FPCFirewallSession object from the Firewall service by using a remote procedure call (RPC).

Syntax

FPCWinsockSession.Refresh()

Remarks

FPCFirewallSession is not a persistent object. There is no persistent storage for this object because its attributes are supplied at run time by ISA. This method uses an RPC to query ISA services about its sessions because this information is dynamic.

Applies To

FPCFirewallSession


FPCFirewallSession.UserName Property

Retrieves the client Windows NT/Windows 2000 account.

Syntax

[sName = ] FPCWinsockSession.UserName

Possible Values

sName
String that specifies the Windows NT/Windows 2000 account of the client.

The property is read-only.

Applies To

FPCFirewallSession


FPCFirewallSession.FirewallSessionConnections Property

Returns a pointer to the FPCFirewallSessionConnections collection.

Syntax

[ collFPCWinsockSessionConnections = ] FPCWinsockSession.WinsockSessionConnections

Possible Values

collFPCWinsockSessionConnections
Reference to the FPCFirewallSessionConnections collection.

The property is read-only.

Applies To

FPCFirewallSession


FPCFirewallSessions Collection

The FPCFirewallSessions collection provides access to a group of FPCFirewallSession objects. This object is a property of the FPCServer object.

Note to C++ Programmers

This collection implements the IFPCFirewallSessions interface.

Methods

The following table lists the methods of the FPCFirewallSessions collection.

Method | Description
Item | Retrieves the given FPCFirewallSession object from the collection.
Refresh | Reads all FPCFirewallSession objects that were not saved by means of an RPC call.

Properties

The following table lists the properties of the FPCFirewallSessions collection.

Property | Description
Count | Retrieves the number of FPCFirewallSession objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFirewallSessions.Count Property

Retrieves the number of FPCFirewallSession objects in the collection.

Syntax

[ iCount = ] FPCWinsockSessions.Count

Possible Values

iCount
Integer that specifies the number of FPCFirewallSession objects.

The property is read-only.

Applies To

FPCFirewallSessions


FPCFirewallSessions.Item Method

Retrieves the given FPCFirewallSession object from the collection.

Syntax

[ vItem = ] FPCWinsockSessions.Item( vUserOrIndex, ClientMachine )

Parameters

vUserOrIndex
Required. Variant that specifies the user name or one-based index of the object to retrieve.
ClientMachine
Optional. Variant that specifies the client machine.

Return Value

vItem
If successful, returns a reference to an object of type FPCFirewallSession. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCFirewallSessions


FPCFirewallSessions.Refresh Method

Reads all the FPCFirewallSession objects from the Firewall service by using a remote procedure call (RPC).

Syntax

FPCWinsockSessions.Refresh()

Remarks

FPCFirewallSession is not a persistent object. There is no persistent storage for this object because its attributes are supplied at run time by ISA. This method uses an RPC call query ISA services about its sessions because this information is dynamic.

Applies To

FPCFirewallSessions


FPCFirewallSessionConnection Object

A Windows Sockets (Winsock) session connection is defined by the client, the computer and the process. One or more connections may be established during a Winsock session. For example, if a client opens three instances of Microsoft Internet Explorer, he has opened three Winsock session connections.

The FPCFirewallSessionConnection object represents a single Winsock session connection. This object is a member of the FPCFirewallSessionConnections collection.

The FPCFirewallSessionConnection object is not represented on the ISA administration tool.

Note to C++ Programmers

This object implements the IFPCFirewallSessionConnection interface.

Methods

The following table lists the methods of the FPCFirewallSessionConnection object.

Method | Description
AbortConnection | Stops the connection.
Refresh | Reads the object configuration from the Firewall service using a remote procedure call, discarding any changes to it that were not saved.

Properties

The following table lists the properties of the FPCFirewallSessionConnection object.

Property | Description
Duration | Retrieves the connection duration.
FirewallConnectionAdditionalInfo | Returns a pointer to the FPCFirewallConnectionAdditionalInfo object, which is reserved for future use.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFirewallSessionConnection.AbortConnection Method

Stops the connection.

Syntax

FPCWinsockSessionConnection.AbortConnection()

Applies To

FPCFirewallSessionConnection


FPCFirewallSessionConnection.Duration Property

Retrieves the connection duration. Each session may have more than one connection, and the connections may have different durations.

Syntax

[ iDuration = ] FPCWinsockSessionConnection.Duration

Possible Values

iDuration
Integer that specifies the session duration.

The property is read-only.

Applies To

FPCFirewallSessionConnection


FPCFirewallSessionConnection.Refresh Method

Reads the object configuration from the Firewall service using a remote procedure call (RPC), discarding any changes to it that were not saved.

Syntax

FPCWinsockSessionConnection.Refresh()

Applies To

FPCFirewallSessionConnection


FPCFirewallSessionConnection.FirewallConnectionAdditionalInfo Property

Returns a pointer to the FPCFirewallConnectionAdditionalInfo object, which is reserved for future use.

Syntax

[oFPCFirewallConnectionAdditionalInfo = ] FPCFirewallSessionConnection.FirewallConnectionAdditionalInfo

Possible Values

oFPCFirewallConnectionAdditionalInfo
Reference to the FPCFirewallConnectionAdditionalInfo object, which is reserved for future use.

The property is read-only.

Applies To

FPCFirewallSessionConnection


FPCFirewallSessionConnections Collection

The FPCFirewallSessionConnections collection provides access to a group of FPCFirewallSessionConnection objects. This object is a property of the FPCFirewallSession object.

Note to C++ Programmers

This collection implements the IFPCFirewallSessionConnections interface.

Methods

The following table lists the methods of the FPCFirewallSessionConnections collection.

Method | Description
Item | Retrieves the given FPCFirewallSessionConnection object from the collection.
Refresh | Reads all the FPCFirewallSessionConnection objects from the Firewall service using a remote procedure call (RPC), discarding any changes to the objects that were not saved.

Properties

The following table lists the properties of the FPCFirewallSessionConnections collection.

Property | Description
Count | Retrieves the number of FPCFirewallSessionConnection objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFirewallSessionConnections.Count Property

Retrieves the number of FPCFirewallSessionConnection objects in the collection.

Syntax

[ iCount = ] FPCWinsockSessionConnections.Count

Possible Values

iCount
Integer that specifies the number of FPCFirewallSessionConnection objects.

The property is read-only.

Applies To

FPCFirewallSessionConnections


FPCFirewallSessionConnections.Item Method

Retrieves the given FPCFirewallSessionConnection object from the collection.

Syntax

[ vItem = ] FPCWinsockSessionConnections.Item ( iIndex )

Parameters

iIndex

Required. Name or integer index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCFirewallSessionConnection. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCFirewallSessionConnections


FPCFirewallSessionConnections.Refresh Method

Reads all the FPCFirewallSessionConnection objects from the Firewall service using a remote procedure call (RPC), discarding any changes to the objects that were not saved.

Syntax

FPCWinsockSessionConnections.Refresh()

Applies To

FPCFirewallSessionConnections


FPCFTPCacheConfiguration Object

The FPCFTPCacheConfiguration object provides access to the FTP cache configuration parameters of an ISA Server. The objects FPCActiveCacheConfiguration, FPCHTTPCacheConfiguration, and FPCFTPCacheConfiguration provide access to all ISA cache configuration settings. These three objects are accessed through properties of the FPCCacheConfiguration object, which serves as a container for the three.

The FPCFTPCacheConfiguration object is a property of an FPCCacheConfiguration object.

Note to C++ Programmers

This object implements the IFPCFTPCacheConfiguration interface.

Methods

The following table lists the methods of the FPCFTPCacheConfiguration object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.
ResetToDefaults | Discards any changes made to the FTP cache configuration and reverts to the default cache configuration.
Save | Saves the FTP cache configuration to persistent storage.

Properties

The following table lists the properties of the FPCFTPCacheConfiguration object.

Property | Description
FTPEnable | Sets or retrieves whether caching of FTP replies is enabled or disabled.
FTPTTLValue | Sets or retrieves the fixed Time to Live (TTL) for FTP cached files.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCFTPCacheConfiguration object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFTPCacheConfiguration.FTPEnable Property

Sets or retrieves whether caching of FTP replies is enabled or disabled.

Syntax

FPCFTPCacheConfiguration.FTPEnable [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Caching of FTP replies is enabled.
FALSE | Caching of FTP replies is disabled.

The property is read-write.

Applies To

FPCFTPCacheConfiguration


FPCFTPCacheConfiguration.FTPTTLValue Property

Sets or retrieves the fixed Time to Live (TTL) for FTP cached files.

Syntax

FPCFTPCacheConfiguration.FTPTTLValue [ = iTTL ]

Possible Values

iTTL
Integer value that specifies the TTL.

The property is read-write.

Applies To

FPCFTPCacheConfiguration


FPCFTPCacheConfiguration.Refresh Method

Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.

Syntax

FPCFTPCacheConfiguration.Refresh()

Applies To

FPCFTPCacheConfiguration


FPCFTPCacheConfiguration.ResetToDefaults Method

Discards any changes made to the cache configuration and reverts to the default cache configuration.

Syntax

FPCFTPCacheConfiguration.ResetToDefaults()

Applies To

FPCFTPCacheConfiguration


FPCFTPCacheConfiguration.Save Method

Saves the FTP cache configuration to persistent storage.

Syntax

FPCFTPCacheConfiguration.Save()

Applies To

FPCFTPCacheConfiguration


FPCFTPCacheConfiguration.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCFTPCacheConfiguration object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCFTPCacheConfiguration.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCFTPCacheConfiguration


FPCHTTPCacheConfiguration Object

The FPCHTTPCacheConfiguration object provides access to the HTTP cache configuration parameters of an ISA server. The objects FPCActiveCacheConfiguration, FPCHTTPCacheConfiguration, and FPCFTPCacheConfiguration provide access to all ISA cache configuration settings. These three objects are accessed through properties of the FPCCacheConfiguration object, which serves as a container for the three.

The FPCHTTPCacheConfiguration object is a property of an FPCCacheConfiguration object.

Note to C++ Programmers

This object implements the IFPCHTTPCacheConfiguration interface.

Methods

The following table lists the methods of the FPCHTTPCacheConfiguration object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.
ResetToDefaults | Discards any changes made to the HTTP cache configuration and reverts to the default cache configuration.
Save | Saves the HTTP cache configuration to persistent storage.

Properties

The following table lists the properties of the FPCHTTPCacheConfiguration object.

Property | Description
AgeFactor | Sets or retrieves the age factor for determining the Time to Live (TTL) of cached HTTP requests.
CacheNon200Responses | Sets or retrieves whether caching of replies whose responses were not OK (200) is enabled or disabled.
CacheWithNoLastModDate | Sets or retrieves whether caching of replies that are missing the modification date is enabled or disabled.
ExpirationPolicy | Sets or retrieves preset values for the cache policy.
HTTPEnable | Sets or retrieves whether caching of HTTP replies is enabled or disabled.
MaxIntervalUnits | Sets or retrieves units in which the MaxIntervalValue property is expressed.
MaxIntervalValue | Sets or retrieves the maximum TTL interval of cached objects originating from HTTP requests.
MinInterval | Sets or retrieves the minimum TTL interval of cached objects originating from HTTP requests.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCHTTPCacheConfiguration object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCHTTPCacheConfiguration.AgeFactor Property

Sets or retrieves the age factor for determining the Time to Live (TTL) of cached HTTP requests.

Syntax

FPCHTTPCacheConfiguration.AgeFactor [ = iFactor ]

Possible Values

iFactor
Integer value that specifies the TTL age factor.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.CacheNon200Responses Property

Sets or retrieves whether caching of replies whose responses were not OK (200) is enabled or disabled.

Syntax

FPCHTTPCacheConfiguration.CacheNon200Responses [ = bEnabled ]

Possible Values

bEnabled
A Boolean value that has either of these settings:
Setting | Meaning
TRUE | Caching of replies with non-OK response is enabled.
FALSE | Caching of replies with non-OK response is disabled.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.CacheWithNoLastModDate Property

Sets or retrieves whether caching of replies that are missing the modification date is enabled or disabled.

Syntax

FPCHTTPCacheConfiguration.CacheWithNoLastModDate [ = bEnabled ]

Possible Values

bEnabled
A Boolean value that has either of these settings:
Setting | Meaning
TRUE | Caching of replies with no modification date is enabled.
FALSE | Caching of replies with no modification date is disabled.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.ExpirationPolicy Property

Sets or retrieves preset values for the cache policy. Setting this property affects the AgeFactor, MaxIntervalValue, and MinInterval properties.

Syntax

FPCHTTPCacheConfiguration.ExpirationPolicy [ = iPolicy ]

Possible Values

iPolicy
A value from the FpcCacheExpirationPolicy enumeration.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.HTTPEnable Property

Sets or retrieves whether caching of HTTP replies is enabled or disabled.

Syntax

FPCHTTPCacheConfiguration.HTTPEnable [ = bEnabled ]

Possible Values

bEnabled
A Boolean value that has either of these settings:
Setting | Meaning
TRUE | Caching of HTTP replies is enabled.
FALSE | Caching of HTTP replies is disabled.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.MaxIntervalUnits Property

Sets or retrieves the units in which the MaxIntervalValue property is expressed.

Syntax

FPCHTTPCacheConfiguration.MaxIntervalUnits [ = iUnits ]

Possible Values

iUnits
Integer value from the FpcTimeScale enumeration.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.MaxIntervalValue Property

Sets or retrieves the maximum Time-to-Live (TTL) interval of cached objects originating from HTTP requests.

Syntax

FPCHTTPCacheConfiguration.MaxIntervalValue [ = iInterval ]

Possible Values

iInterval
Integer value that specifies the maximum TTL interval. The interval is specified in units determined by the value of the MaxIntervalUnits property.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.MinInterval Property

Sets or retrieves the minimum Time-to-Live (TTL) interval of cached objects originating from HTTP requests.

Syntax

FPCHTTPCacheConfiguration.MinInterval [= iInterval ]

Possible Values

iInterval
Integer value that specifies the minimum TTL interval, in minutes.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.Refresh Method

Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.

Syntax

FPCHTTPCacheConfiguration.Refresh()

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.ResetToDefaults Method

Discards any changes made to the cache configuration and reverts to the default cache configuration.

Syntax

FPCHTTPCacheConfiguration.ResetToDefaults()

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.Save Method

Saves the HTTP cache configuration to persistent storage.

Syntax

FPCHTTPCacheConfiguration.Save()

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCHTTPCacheConfiguration object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCHTTPCacheConfiguration.VendorParametersSets

Possible Values

collFPCtVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCHTTPCacheConfiguration


FPCIpPacketFilter Object

The FPCIpPacketFilter object represents a single IP packet filter object of an ISA domain array, either an allowing or blocking filter. An IP packet filter monitors all network traffic to determine whether the packets can be communicated. If the packet passes through the filter, the data is then passed up to the application layer.

FPCIpPacketFilter is a member of the FPCIpPacketFilters collection.

Note to C++ Programmers

This object implements the IFPCIpPacketFilter interface.

Methods

The following table lists the methods of the FPCIpPacketFilter object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.
Save | Saves the object's configuration information to persistent storage.
SetLocalHost | Sets the type and IP values of the local host.
SetRemoteHost | Sets the type and IP values of the remote host.

Properties

The following table lists the properties of the FPCIpPacketFilter object.

Property | Description
AllServers | Sets or retrieves whether the filter applies to all the servers in the domain array.
Description | Sets or retrieves the description of the IP packet filter.
Enabled | Sets or retrieves whether the filter is enabled.
FilterKind | Sets or retrieves the kind of filter, either an allowing or blocking filter.
FilterType | Sets or retrieves the type of the filter.
ICMPCodeNumber | Sets or retrieves the Internet Control Message Protocol (ICMP) code number used by the filter.
ICMPCodeOption | Sets or retrieves the kind of Internet Control Message Protocol (ICMP) code used by the filter.
ICMPTypeNumber | Sets or retrieves the Internet Control Message Protocol (ICMP) type number used by the filter.
ICMPTypeOption | Sets or retrieves the kind of Internet Control Message Protocol (ICMP) type attribute used by the filter.
LocalHostIPAddress | Retrieves the the DNS name (IP address or host name) of the local host.
LocalHostIPMask | Retrieves the IP mask of the local host.
LocalHostType | Retrieves the type of local host used by the filter.
LocalPortNumber | Sets or retrieves the local port number used by the filter.
LocalPortType | Sets or retrieves the type of local port used by the filter.
LogMatchingPackets | Sets or retrieves whether the filter will log packets that match its parameters.
Name | Sets or retrieves the name of the IP packet filter.
PacketDirection | Sets or retrieves the direction of packets monitored by the filter.
ProtocolNumber | Sets or retrieves the IP protocol monitored by the filter.
RemoteHostIPAddress | Retrieves the DNS name (IP address or host name) of the remote host.
RemoteHostIPMask | Retrieves the IP mask of the remote host.
RemoteHostType | Retrieves the type of remote host used by the filter.
RemotePortNumber | Sets or retrieves the remote port number used by the filter.
RemotePortType | Sets or retrieves the type of remote port used by the filter.
ServerName | Sets or retrieves the name of the specific server to which this filter applies.
VendorParametersSets | Retrieves a reference to an object used to access a vendor's data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCIpPacketFilter.AllServers Property

Sets or retrieves whether the filter applies to all servers in the domain array.

Syntax

FPCIpPacketFilter.AllServers [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of two settings:
Setting | Meaning
TRUE | Filter applies to all servers in the domain array.
FALSE | Filter applies only to the server whose name can be found through the ServerName property.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.Description Property

Sets or retrieves the description of the IP packet filter.

Syntax

FPCIpPacketfilter.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the IP packet filter description.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.Enabled Property

Sets or retrieves whether the filter is enabled.

Syntax

FPCIpPacketFilter.Enabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of two settings:
Setting | Meaning
TRUE | Filter is enabled.
FALSE | Filter is disabled.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.FilterKind Property

Sets or retrieves the kind of the filter, either an allowing or blocking filter. The filter will be a predefined filter or a custom filter.

Syntax

FPCIpPacketfilter.FilterMode [ = PFFilterMode ]

Possible Values

PFFilterMode
Filter mode. It can have a value from the FpcPfFilterMode enumerated type.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.FilterType Property

Sets or retrieves the type of filter, such as a predefined or custom type.

Syntax

FPCIpPacketfilter.FilterType [ = PFFilterType ]

Possible Values

PFFilterType
Filter type. It can have a value from the FpcPfFilterType enumeration.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.ICMPCodeNumber Property

Sets or retrieves the Internet Control Message Protocol (ICMP) code number used by the filter. It can have a value from 0 to 255. ICMP code is a subdescriptor of the ICMP type.

Syntax

FPCIpPacketFilter.ICMPCodeNumber[ = lICMPCodeNumber ]

Possible Values

lICMPCodeNumber
Long value that specifies the ICMP code number.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.ICMPCodeOption Property

Sets or retrieves the kind of Internet Control Message Protocol (ICMP) code used by the filter.

Syntax

FPCIpPacketFilter.ICMPCodeOption [ = PFICMPCodeOption ]

Possible Values

PFICMPCodeOption
ICMP code option. It can have a value from the FpcPFICMPCodeOptions enumerated type.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.ICMPTypeNumber Property

Sets or retrieves the Internet Control Message Protocol (ICMP) type number used by the filter. It can have a value from 0 to 255.

Syntax

FPCIpPacketFilter.ICMPTypeNumber[ = lICMPTypeNumber ]

Possible Values

lICMPTypeNumber
Long value that specifiies the ICMP type number.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.ICMPTypeOption Property

Sets or retrieves the kind of Internet Control Message Protocol (ICMP) type attribute used by the filter.

Syntax

FPCIpPacketFilter.ICMPTypeOption [ = PFICMPTypeOption ]

Possible Values

PFICMPTypeOption
ICMP type option. It can have a value from the FpcPFICMPTypeOptions enumerated type:

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.LocalHostIPAddress Property

Retrieves the the Domain Name System (DNS) name (IP address or host name) of the local host.

Syntax

[ sLocalHostIPAddress = ] FPCIpPacketFilter.LocalHostIPAddress

Possible Values

sLocalHostIPAddress
String that specifies the local host IP address.

The property is read only.

Remarks

This property is read-only, but the value of LocalHostIPAddress can be set using the SetLocalHost method.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.LocalHostIPMask Property

Retrieves the IP mask of the local host when the latter contains a range of computers.

Syntax

[ sLocalHostIPMask = ] FPCIpPacketFilter.LocalHostIPMask

Possible Values

sLocalHostIPMask
Returns a string value that specifies the local host IP mask.

The property is read-only.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.LocalHostType Property

Retrieves the type of local host used by the filter.

Syntax

[ PFLocalHostType = ] FPCIpPacketFilter.LocalHostType

Possible Values

PFLocalHostType
The local host type. It can have a value from the FpcPFLocalHostType enumerated type.

The property is read-only.

Remarks

This property is read-only, but the value of LocalHostType can be set using the SetLocalHost method.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.LocalPortNumber Property

Sets or retrieves the local port number used by the filter, within the allowed port range of 1 to 65535.

Syntax

FPCIpPacketFilter.LocalPortNumber[ = lLocalPortNumber ]

Possible Values

lLocalPortNumber
Long value that specifies the local port number.

The property is read-write.

Remarks

When the RemotePortType property is set to the fpcPfAnyPort or the fpcPfDynamicPort value of the FpcPFLocalPortType enumeration, this property becomes meaningless.

Applies To

FPCIpPacketFilter

See also

LocalPortType


FPCIpPacketFilter.LocalPortType Property

Sets or retrieves the type of local port. This port can be allowed or blocked by the filter according to the kind of filter (allowing or blocking).

Syntax

FPCIpPacketFilter.LocalPortType [ = PFLocalPortType ]

Possible Values

PFLocalPortType
The local port type. It can have a value from the FpcPFLocalPortType enumerated type.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.LogMatchingPackets Property

Sets or retrieves whether the filter will log packets that match its parameters. This applies to blocking filters only.

Syntax

FPCIpPacketFilter.LogMatchingPackets [ = bLogMatchingPackets ]

Possible Values

bLogMatchingPackets
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Filter will log packets that it matches.
FALSE | Filter will not log packet that it matches.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.Name Property

Sets or retrieves the name of the IP packet filter.

Syntax

FPCIpPacketfilter.Name [ = sName ]

Possible Values

sName
String that specifies the IP packet filter name.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.PacketDirection Property

Sets or retrieves the direction of packets that are allowed or blocked as specified by the filter type.

Syntax

FPCIpPacketFilter.PacketDirection [ = PacketDirectionType ]

Possible Values

PacketDirectionType
The packet direction. It can have a value from the FpcPFDirectionType enumerated type.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.ProtocolNumber Property

Sets or retrieves the Internet Protocol (IP) monitored by the filter. (The protocol can be TCP, UDP, ICMP, or another type.)

Syntax

FPCIpPacketfilter.ProtocolNumber [ = FpcProtocolNumber ]

Possible Values

FpcProtocolNumber
The protocol number. It can be an IP protocol number of the range 0-255, or have a value from the FpcPFProtocolType enumerated type.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.Refresh Method

Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.

Syntax

FPCIpPacketFilter.Refresh()

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.RemoteHostIPAddress Property

Retrieves the the Domain Name System (DNS) name (IP address or host name) of the remote host.

Syntax

[ sRemoteHostIPAddress = ] FPCIpPacketFilter.RemoteHostIPAddress

Possible Values

sRemoteHostIPAddress
String specifying the remote host IP address.

The property is read only.

Remarks

This property is read-only, but RemoteHostIPAddress can be set by using the SetRemoteHost method.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.RemoteHostIPMask Property

Retrieves the Internet Protocol (IP) mask of the remote host, but only when a mask is needed, as in the case of a subnet remote host.

Syntax

[ sRemoteHostIPMask = ]  FPCIpPacketFilter.RemoteHostIPMask

Possible Values

sRemoteHostIPMask
String value that specifies the remote host IP mask.

The property is read only.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.RemoteHostType Property

Retrieves the type of remote host used by the filter.

Syntax

[ PFRemoteHostType = ] FPCIpPacketFilter.RemoteHostType

Possible Values

PFRemoteHostType
The remote host type. It can have a value of the FpcPFRemoteHostType enumerated type.

The property is read-only.

Remarks

This property is read-only, but RemoteHostType can be set by using the SetRemoteHost method.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.RemotePortNumber Property

Sets or retrieves the remote port number used by the filter, within the allowed port range of 1 to 65535.

Syntax

FPCIpPacketFilter.RemotePortNumber [ = lRemotePortNumber ]

Possible Values

lRemotePortNumber
Long value that specifies the remote port number.

The property is read-write.

Remarks

When the RemotePortType property is set to fpcPfAnyPort, RemotePortNumber becomes meaningless.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.RemotePortType Property

Sets or retrieves the type of remote port. This port can be allowed or blocked by the filter.

Syntax

FPCIpPacketFilter.RemotePortType [ = PFRemotePortType ]

Possible Values

PFRemotePortType
The remote port type. It can have one a value of the FpcPFRemotePortType enumerated type.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.Save Method

Saves the object's configuration information to persistent storage.

Syntax

FPCIpPacketFilter.Save()

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.ServerName Property

Sets or retrieves the name of the specific server for which this filter applies. This property is only valid when AllServers is not set to TRUE, meaning the filter applies to all servers in the domain array.

Syntax

FPCIpPacketfilter.ServerName [ = sName ]

Possible Values

sName
String that specifies the server name.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.SetLocalHost Method

Sets the type and IP values of the local host.

Syntax

FPCIpPacketFilter.SetLocalHost( LocalHostType, newIPAddress, sNewIPMask )

Parameters

LocalHostType
The local host type. It can have a value of the FpcPFLocalHostType enumerated type.
newIPAddress
Optional. The name or IP address of the local host.
sNewIPMask
Optional. String that specifies the mask of the local host.

Applies To

FPCIpPacketFilter

See Also

LocalHostType, LocalHostIPAddress


FPCIpPacketFilter.SetRemoteHost Method

Sets the type and IP values of the remote host.

Syntax

FPCIpPacketFilter.SetRemoteHost( RemoteHostType, newIPAddress, sNewIPMask )

Parameters

RemoteHostType
The local host type. It can have s value of the FpcPFRemoteHostType enumerated type.
newIPAddress
Optional. The name or IP address of the remote host.
sNewIPMask
Optional. String that specifies the mask of the remote host.

Applies To

FPCIpPacketFilter

See Also

RemoteHostType, RemoteHostIPAddress


FPCIpPacketFilter.VendorParametersSets Property

Retrieves a reference to an object that is used to access a vendor's data.

Syntax

[ collFPCVendorParametersSets = ] FPCIpPacketFilter.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCIpPacketFilter


FPCIpPacketFilters Collection

The FPCIpPacketFilters collection provides access to a group of IP packet filter objects in an ISA domain array. An IP packet filter monitors all network traffic to determine whether the packets can be communicated. If the packet passes through the filter, the data is then passed up to the application layer. An individual IP packet filter will be either an allowing or blocking filter. Allowing filters permit communication between specified IP addresses by using the specified protocols and ports. Blocking filters block communication between specified IP addresses by using the specified protocols and ports.

This collection is a property of an FPCEnterprisePolicy object and an FPCArrayPolicy object.

Note to C++ Programmers

This collection implements the IFPCIpPacketFilters interface.

Methods

The following table lists the methods of the FPCIpPacketFilters collection.

Method | Description
Add | Creates a new FPCIpPacketFilter object in the collection and returns a reference to it.
Item | Retrieves the given FPCIpPacketFilter object from the collection.
Refresh | Reads the state of all IP packet filters from the persistent storage, discarding any changes to the current state that were not saved.
Remove | Removes an IP packet filter object from the collection.
Save | Saves the state of the IP packet filters to persistent storage.

Properties

The following table lists the properties of the FPCIpPacketFilters collection.

Property | Description
Count | Retrieves the number of FPCIpPacketFilter objects in the collection.
Enabled | Sets or retrieves whether IP packet filtering is enabled.
IntrusionDetectionEnabled | Sets or retrieves whether the Intrusion Detection setting is enabled.
IpFragmentsFilteringEnabled | Sets or retrieves whether IP fragment filters are enabled.
IpHalfScanDetectionEnabled | Sets or retrieves whether Internet Protocol (IP) half-scan attacks will be detected and generate an event.
IpOptionPacketFilteringEnabled | Sets or retrieves whether IP packet filters are enabled.
IpRoutingEnabled | Sets or retrieves whether Internet Protocol (IP) routing is enabled.
LandAttackDetectionEnabled | Sets or retrieves whether land attacks will be detected and generate an event.
PingOfDeathDetectionEnabled | Sets or retrieves whether ping-of-death attacks will be detected and generate an event.
PortScanDetectionAllPortsThreshold | Sets or retrieves, if detection of port scan attacks is enabled, the total number of ports that can be scanned before ISA generates an alert.
PortScanDetectionDistinctPortsThreshold | If detection of port scan attacks is enabled, this property sets or retrieves the total number of well-known ports that can be scanned before ISA generates an alert.
PortScanDetectionEnabled | Sets or retrieves whether port scan attacks will be detected and generate an event.
UdpBombDetectionEnabled | Sets or retrieves whether User Datagram Protocol (UDP) bomb attacks will be detected and generate an event.
VendorParametersSets | Retrieves a reference to an object for storing and loading of custom data into the FPCIpPacketFilters collection's storage.
WinOutOfBandDetectionEnabled | Sets or retrieves whether Windows out-of-band attacks will be detected and generate an event.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCIpPacketFilters.Add Method

Creates a new FPCIpPacketFilter object in the collection and returns a reference to it.

Syntax

[ oFPCIpPacketFilter = ] FPCIpPacketFilters.Add( sName )

Parameters

sName
Required. String that specifies the name of the new filter.

Return Value

oFPCIpPacketFilter
Returns a reference to the new FPCIpPacketFilter object.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.Count Property

Retrieves the number of FPCIpPacketFilter objects in the collection.

Syntax

[ iCount = ] FPCIpPacketFilters.Count

Possible Values

iCount
Integer value that specifies the number of FPCIpPacketFilter objects.

The property is read-only.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.Enabled Property

Sets or retrieves whether IP packet filtering is enabled.

Note When you've changed the setting by using the Enabled property, and have saved changes by using the Save method, the firewall and Web proxy (w3proxy) services must be restarted in order for your change to take effect. To stop and restart the services use the FPCArray.SendRestartNotification Method.

Syntax

FPCIpPacketFilters.Enabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | IP packet filtering is enabled.
FALSE | IP packet filtering is disabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.IntrusionDetectionEnabled Property

Sets or retrieves whether the Intrusion Detection setting is enabled.

Syntax

FPCIpPacketFilters.IntrusionDetectionEnabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Intrusion detection is enabled.
FALSE | Intrusion detection is disabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.IpFragmentsFilteringEnabled Property

Sets or retrieves whether IP fragment filtering is enabled. If IP fragment filtering is enabled, datagram fragments are filtered.

Syntax

FPCIpPacketFilters.IpFragmentsFilteringEnabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | IP fragment filtering is enabled.
FALSE | IP fragment filtering is disabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.IpHalfScanDetectionEnabled Property

Sets or retrieves whether Internet Protocol (IP) half-scan attacks will be detected and generate an event.

Syntax

FPCIpPacketFilters.IpHalfScanDetectionEnabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Detection of IP half scan attacks is enabled.
FALSE | Detection of IP half scan attacks is disabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.IpOptionPacketFilteringEnabled Property

Sets or retrieves whether this filtering option is enabled. IP option filtering is the filtering of all IP traffic with "IP options" added to the IP header.

Syntax

FPCIpPacketFilters.IpOptionPacketFilteringEnabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Filtering IP packets with options is enabled.
FALSE | Filtering IP packets with options is disabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.IpRoutingEnabled Property

Sets or retrieves whether Internet Protocol (IP) routing is enabled.

Note It is not recommended to enable IP routing without enabling packet filtering.

Syntax

FPCIpPacketFilters.IpRoutingEnabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | IP Routing is enabled.
FALSE | IP Routing is disabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.Item Method

Retrieves the given FPCIpPacketFilter object from the collection.

Syntax

[ vItem = ] FPCIpPacketfilters.Item( vIndex )

Parameters

vIndex
Required. Name or index that specifies the one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCIpPacketFilter. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.LandAttackDetectionEnabled Property

Sets or retrieves whether land attacks will be detected and generate an event.

Syntax

FPCIpPacketFilters.LandAttackDetectionEnabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Detection of land attacks is enabled.
FALSE | Detection of land attacks is disabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.PingOfDeathDetectionEnabled Property

Sets or retrieves whether ping-of-death attacks will be detected and generate an event.

Syntax

FPCIpPacketFilters.PingOfDeathDetectionEnabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Detection of ping-of-death attacks is enabled.
FALSE | Detection of ping-of-death attacks is disabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.PortScanDetectionAllPortsThreshold Property

Sets or retrieves, if detection of port scan attacks is enabled, the total number of ports that can be scanned before ISA generates an alert.

Syntax

FPCIpPacketFilters.PortScanDetectionAllPortsThreshold [ = lAllPorts ]

Possible Values

lAllPorts
Long value that specifies the number of ports.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.PortScanDetectionDistinctPortsThreshold Property

If detection of port scan attacks is enabled, this property sets or retrieves the total number of well-known ports that can be scanned before ISA generates an alert.

Syntax

FPCIpPacketFilters.PortScanDetectionDistinctPortsThreshold [ = lWellKnownPorts ]

Possible Values

lWellKnownPorts
Long value that specifies the number of well-known ports.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.PortScanDetectionEnabled Property

Sets or retrieves whether port scan attacks will be detected and generate an event.

Syntax

FPCIpPacketFilters.PortScanDetectionEnabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Detection of port scan attacks is enabled.
FALSE | Detection of port scan attacks is disabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.Refresh Method

Reads the state of all IP packet filters from persistent storage, discarding any changes to the current state that were not saved.

Syntax

FPCIpPacketFilters.Refresh()

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.Remove Method

Removes an IP packet filter object from the collection.

Syntax

FPCIpPacketFilters.Remove( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to remove.

Applies To

FPCIpPacketFilters

See Also

FPCIpPacketFilter


FPCIpPacketFilters.Save Method

Saves the state of the IP packet filters to persistent storage.

Syntax

FPCIpPacketFilters.Save()

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.UdpBombDetectionEnabled Property

Sets or retrieves whether User Datagram Protocol (UDP) bomb attacks will be detected and generate an event.

Syntax

FPCIpPacketFilters.UdpBombDetectionEnabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Detection of UDP bomb attacks is enabled.
FALSE | Detection of UDP bomb attacks is disabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCIpPacketFilter object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCIpPacketFilters.VendorParametersSets

Possible Values

collFPCtVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.WinOutOfBandDetectionEnabled Property

Sets or retrieves whether Windows out-of-band attacks will be detected and generate an event.

Syntax

FPCIpPacketFilters.WinOutOfBandDetectionEnabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Detection of Windows out-of-band attacks is enabled.
FALSE | Detection of Windows out-of-band attacks is disabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpRange Object

The FPCIpRange object defines a range of IP addresses defined by a lower bound and an upper bound. The lower and upper bounds are set with the IP_From and IP_To properties. This object is created by setting an IP range for a client address set. Client address sets are ISA policy elements.

The FPCIpRange object is a property of the FPCClientAddressSet object.

Note to C++ Programmers

This object implements the IFPCIpRange interface.

Methods

The following table lists the methods of the FPCIpRange object.

Method | Description
Refresh | Reads all of the items from persistent storage, discarding any changes to the current rules that were not saved.
Save | Saves all the items in the collection to persistent storage.
SetIps | Sets the bounds of the IP range.

Properties

The following table lists the properties of the FPCIpRange object.

Property | Description
IP_From | Retrieves the lower bound of the IP range.
IP_To | Retrieves the upper bound of the IP range.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCIpRange.IP_From Property

Retrieves the lower bound of the IP range.

Syntax

[ sFrom ] = FPCIpRange.IP_From

Possible Values

sFrom
String that specifies the lower bound.

The property is read only.

Applies To

FPCIpRange


FPCIpRange.IP_To Property

Retrieves the upper bound of the IP range.

Syntax

[ sTo = ] FPCIpRange.IP_To

Possible Values

sTo
String that specifies the upper bound.

The property is read only.

Applies To

FPCIpRange


FPCIpRange.Refresh Method

Reads all the items from persistent storage, discarding any changes that were not saved.

Syntax

FPCIpRange.Refresh()

Applies To

FPCIpRange


FPCIpRange.Save Method

Saves all items in the collection to persistent storage.

Syntax

FPCIpRange.Save()

Applies To

FPCIpRange


FPCIpRange.SetIps Method

Sets the bounds of the IP range.

Syntax

FPCIpRange.SetIps ( sIp_From, sIp_To )

Possible Values

sIp_From
String that specifies the lower bound of the IP range.
sIp_To
String that specifies the upper bound of the IP range.

Applies To

FPCIpRange


FPCLAT Collection

The FPCLAT collection represents the Local Address Table (LAT) of the ISA domain array. FPCLAT holds a collection of FPCLATEntry objects, each representing one entry in the table. The LAT is a table of all internal IP address ranges used by the internal network behind the ISA server. ISA Server uses the LAT to control the way computers on the internal network communicate with external networks.

This collection is a property of the FPCNetworkConfiguration object.

Note to C++ Programmers

This collection implements the IFPCLAT interface.

Note

When you've made and saved changes to the LAT that will affect the state of the external or internal Network Interface Card (NIC), the firewall and Web proxy (w3proxy) services must be restarted in order for your change to take effect. To stop and restart the services use the FPCArray.SendRestartNotification Method.

Methods

The following table lists the methods of the FPCLAT collection.

Method | Description
Add | Creates a new entry in the LAT and returns a reference to it.
AddFromAllCards | Adds to the LAT all the ranges accessible through all network interface cards (NICs) of a specific server, according to the Windows 2000 routing table.
AddFromSelectedAdapters | Adds to the LAT containing all the ranges accessible through the selected network interface cards of a specific server according to the Windows 2000 routing table.
AddPrivateRanges | Adds the private ranges 10.x.x.x, 192.168.x.x. and 172.16.x.x - 172.31.x.x to the LAT.
Clear | Clears the LAT. All entries are removed.
IsIpInternal | Returns a Boolean value that specifies whether an Internet Protocol (IP) is internal.
Item | Retrieves the given FPCLATEntry object from the collection.
Refresh | Reads all the LAT information from persistent storage, discarding any changes to the current LAT object that were not saved.
Remove | Removes a LAT entry object from the collection.
Save | Saves the LAT information to persistent storage.

Properties

The following table lists the properties of the FPCLAT collection.

Property | Description
Count | Retrieves the number of LAT entries in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading of custom data into the FPCLAT collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCLAT.Add Method

Creates a new entry in the Local Address Table (LAT) and returns a reference to it.

Syntax

[ oFPCLATEntry = ] FPCLAT.Add( sFrom, sTo )

Parameters

sFrom
Required. String that specifies the lower IP address of the range.
sTo
Required. String that specifies the higher IP address of the range.

Return Value

oFPCLATEntry
Returns a reference to the new FPCLATEntry object.

Applies To

FPCLAT


FPCLAT.AddFromAllCards Method

Adds to the LAT all the ranges accessible through all network interface cards (NICs) of a specific server, according to the Windows 2000 routing table.

Syntax

FPCLAT.AddFromAllCards( sServerName )

Parameters

sServerName
String that specifies the name of the server whose IP addresses, from all its NICs, should be added to the LAT. If no server is specified, this method will add the IP addresses from the current server to the LAT.

Applies To

FPCLAT

See Also

AddFromSelectedAdapters


FPCLAT.AddFromSelectedAdapters Method

Adds to the LAT the IP ranges that are accessible through selected network interface cards (NICs). The additional IP ranges are taken from the server specified by the sServerName parameter. The selected NICs are specified by manipulating the AdapterList property of the corresponding FPCServer object.

Syntax

FPCLAT.AddFromSelectedAdapters( sServerName )

Parameters

sServerName
String that specifies the name of the server whose IP addresses, from its selected NICs, should be added to the LAT. If no server is specified, the IP addresses from the current server will be added to the LAT.

Applies To

FPCLAT

See Also

AddFromAllCards


FPCLAT.AddPrivateRanges Method

Adds the private ranges 10.x.x.x, 192.168.x.x. and 172.16.x.x - 172.31.x.x to the Local Address Table (LAT).

Syntax

FPCLAT.AddPrivateRanges()

Applies To

FPCLAT


FPCLAT.Clear Method

Clears the Local Address Table (LAT). All entries are removed.

Syntax

FPCLAT.Clear()

Applies To

FPCLAT


FPCLAT.Count Property

Retrieves the number of FPCLATEntry objects in the collection.

Syntax

[ iCount = ] FPCLAT.Count

Possible Values

iCount
Integer value that specifies the number of FPCLATEntry objects.

The property is read-only.

Applies To

FPCLAT


FPCLAT.IsIpInternal Method

Returns a Boolean value that specifies whether an Internet Protocol (IP) is internal.

Syntax

[ bIsInternal = ] FPCLAT.IsIpInternal()

Return Value

bIsInternal
Boolean value that specifies whether the IP is internal.

Applies To

FPCLAT


FPCLAT.Item Method

Retrieves the given FPCLATEntry object from the collection.

Syntax

[ vItem = ] FPCLAT.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCLATEntry. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCLAT


FPCLAT.Refresh Method

Reads all the Local Address Table (LAT) information from persistent storage, discarding any changes to the current FPCLATEntry object that were not saved.

Syntax

FPCLAT.Refresh()

Applies To

FPCLAT


FPCLAT.Remove Method

Removes an FPCLATEntry object from the collection.

Syntax

FPCLAT.Remove( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to remove.

Applies To

FPCLAT


FPCLAT.Save Method

Saves the Local Address Table (LAT) information to persistent storage.

Syntax

FPCLAT.Save()

Applies To

FPCLAT


FPCLAT.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCLAT collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCLAT.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCLAT


FPCLATEntry Object

Each FPCLATEntry object represents a single entry in the Local Address Table (LAT) of the ISA array. The LAT contains all internal IP address ranges used by the internal network behind the ISA Server computer. ISA Server uses the LAT to determine how computers on the internal network communicate with each other and with external networks.

This object is a part of the FPCLAT collection, which represents the entire table.

Note to C++ Programmers

This object implements the IFPCLATEntry interface.

Methods

The following table lists the methods of the FPCLATEntry object.

Method | Description
Refresh | Reads the LAT entry information from persistent storage, discarding any changes to the current LAT entry object that were not saved.
Save | Saves the LAT information to persistent storage.
SetFromTo | Sets the IP address range of this LAT entry. Sets both the From (start of range) and the To (end of range).

Properties

The following table lists the properties of the FPCLATEntry object.

Property | Description
Description | Retrieves the description of the LAT entry.
IP_From | Retrieves the lower IP address of the range.
IP_To | Retrieves the higher IP address of the range.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCLATEntry object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCLATEntry.Description Property

Sets or etrieves the description of the LAT entry.

Syntax

FPCLATEntry.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the LAT entry.

The property is read-write.

Applies To

FPCLATEntry


FPCLATEntry.IP_From Property

Retrieves the lower IP address of the range.

Syntax

[ sFrom = ] FPCLATEntry.IP_From

Possible Values

sFrom
String that specifies the lower IP address.

The property is read-only.

Applies To

FPCLATEntry

See Also

IP_To


FPCLATEntry.IP_To Property

Retrieves the higher IP address of the range.

Syntax

[ sTo = ] FPCLATEntry.IP_To

Possible Values

sTo
String that specifies the higher IP address.

The property is read-only.

Applies To

FPCLATEntry

See Also

IP_From


FPCLATEntry.Refresh Method

Reads the LAT entry information from persistent storage, discarding any changes to the current FPCLATEntry object that were not saved.

Syntax

FPCLATEntry.Refresh()

Applies To

FPCLATEntry


FPCLATEntry.Save Method

Saves the LAT information to persistent storage.

Syntax

FPCLATEntry.Save()

Applies To

FPCLATEntry


FPCLATEntry.SetFromTo Method

Sets the IP address range of this Local Address Table (LAT) entry. Sets both the From IP address (start of range) setting and the To IP address (end of range) setting.

Syntax

FPCLATEntry.SetFromTo( sNewFrom, sNewTo )

Parameters

sNewFrom
New To IP address.
sNewTo
New From IP address.

Applies To

FPCLATEntry


FPCLATEntry.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCLATEntry object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCLATEntry.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCLATEntry


FPCLDT Collection

The FPCLDT collection provides access to all the FPCLDTEntry objects of an ISA Server computer. Through this collection you can add, delete, and modify individual entries of the Local Domain Table (LDT). An LDT lists each computer, with a dot in its name, that is located in the internal network behind the ISA server.

Each entry in the table is stored as an individual FPCLDTEntry object.

The FPCLDT collection is a property of the FPCNetworkConfiguration object.

Note to C++ Programmers

This collection implements the IFPCLDT interface.

Methods

The following table lists the methods of the FPCLDT collection.

Method | Description
Add | Creates a new LDTEntry object in the list and returns a reference to it.
Item | Retrieves the given LDTEntry object from the collection.
Refresh | Reads all the items from the persistent storage, discarding any changes to the current LDT entries that were not saved.
Remove | Removes an LDTEntry object from the collection.
Save | Saves all the items in the collection to persistent storage.

Properties

The following table lists the properties of the FPCLDT collection.

Property | Description
Count | Retrieves the number of LDTEntry objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading of custom data in the LDT collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCLDT.Add Method

Creates a new FPCLDTEntry object in the list and returns a reference to it. The Save method must be called to save the added FPCLDTEntry object to persistent storage.

Syntax

[ oFPCLDTEntry = ] FPCLDT.Add( sDomainName )

Parameters

sDomainName
Required. String that specifies the name of the new LDT entry.

Return Value

oFPCLDTEntry
Returns a reference to an FPCLDTEntry object.

Applies To

FPCLDT


FPCLDT.Count Property

Retrieves the number of FPCLDTEntry objects in the collection.

Syntax

[ iCount = ] FPCLDT.Count

Possible Values

iCount
Integer value that specifies the number of FPCLDTEntry objects.

The property is read-only.

Applies To

FPCLDT


FPCLDT.Item Method

Retrieves the FPCLDTEntry object specified by the index parameter.

Syntax

[ vItem = ] FPCLDT.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCLDTEntry. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCLDT


FPCLDT.Refresh Method

Reads all items in the collection from persistent storage, discarding any changes to the current Local Domain Table (LDT) that were not saved.

Syntax

FPCLDT.Refresh()

Applies To

FPCLDT


FPCLDT.Remove Method

Removes the FPCLDTEntry object from the collection specified by the index parameter.

Syntax

FPCLDT.Remove( vItem )

Parameters

vItem
Required. One-based index or name of the object to remove.

Applies To

FPCLDT


FPCLDT.Save Method

Saves all items in the collection to persistent storage. It is important to remember that no changes will be saved unless the Save method is called.

Syntax

FPCLDT.Save()

Applies To

FPCLDT


FPCLDT.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCLDT collection's storage. The VendorParametersSets property is designed to allow third-party extensions to be integrated into ISA.

Syntax

[ collFPCVendorParametersSets = ] FPCLDT.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCLDT

See Also

FPCLDTEntry


FPCLDTEntry Object

The FPCLDTEntry object represents a single entry in the Local Domain Table (LDT). You can modify individual LDT entries using this object. An LDT lists all the servers in the internal network behind the ISA server.

This object is a member of the FPCLDT collection.

Note to C++ Programmers

This object implements the IFPCLDTEntry interface.

Methods

The following table lists the methods of the FPCLDTEntry object.

Method | Description
Refresh | Reads the object's data from persistent storage, discarding any changes to the data that were not saved.
Save | Saves all the object's data to persistent storage.

Properties

The following table lists the properties of the FPCLDTEntry object.

Property | Description
Description | Sets or retrieves the name of the domain.
Name | Sets or retrieves the name of the domain.
VendorParametersSets | Retrieves a reference to an object for storing and loading of custom data into the FPCLDTEntry object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCLDTEntry.Description Property

Sets or retrieves the name of the domain. You can use this property to change domains in the Local Domain Table (LDT) programmatically.

Syntax

FPCLDTEntry.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the domain.

The property is read-write.

Applies To

FPCLDTEntry


FPCLDTEntry.Name Property

Sets or retrieves the name of the object.

Syntax

FPCLDTEntry.Name [ = sName ]

Possible Values

sName
String that specifies the name of the domain.

The property is read-write.

Applies To

FPCLDTEntry


FPCLDTEntry.Refresh Method

Reads the object's data from persistent storage, discarding any changes to the data that were not saved.

Syntax

FPCLDTEntry.Refresh()

Applies To

FPCLDTEntry


FPCLDTEntry.Save Method

Saves all the object's data to persistent storage.

Syntax

FPCLDTEntry.Save()

Applies To

FPCLDTEntry


FPCLDTEntry.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCLDTEntry object's storage. The VendorParametersSets property is designed to allow third-party extensions to be integrated into ISA.

Syntax

[ collFPCVendorParametersSets = ] FPCLDTEntry.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCLDTEntry


FPCListenEntries Collection

The FPCListenEntries collection provides access to a group of FPCListenEntry objects. Each FPCListenEntry object defines an IP and a port on which the forward proxy or reverse proxy listens. These settings are manipulated by means of the IP property of each FPCListenEntry object.

This object is a property of the FPCWebProxy object.

Note to C++ Programmers

This collection implements the IFPCListenEntries interface.

Note

When you've made and saved changes to the port numbers that the Web proxy (w3proxy) service listens on, the w3proxy service must be restarted in order for your change to take effect. To stop and restart the w3proxy service use the FPCArray.SendRestartNotification Method.

Methods

The following table lists the methods of the FPCListenEntries collection.

Method | Description
Add | Adds a new FPCListenEntry object.
Item | Retrieves the given FPCListenEntry object from the collection.
Refresh | Reads all the listen entry objects from persistent storage.
Remove | Removes an item from the collection.
Save | Saves the entries data to persistent storage.

Properties

The following table lists the properties of the FPCListenEntries collection.

Property | Description
AllBasicAuthentication | Sets or retrieves the authentication access of the proxy.
AllDigestAuthentication | Sets or retrieves the authentication access of the proxy.
AllDomain | Sets or retrieves a string value that specifies the domain for authentication.
AllIntegratedWindowsAuthentication | Sets or retrieves the authentication access of the proxy.
AllSSLCertificateAuthentication | Sets or retrieves how the proxy handles all certificate authentication.
AllSSLServerCertificate | Sets or retrieves an FPCSSLCertificate object that represents the client certificate to use when authenticating against the client.
Count | Retrieves the number of entries in the collection.
Description | Sets or returns the description of the collection of listen entries.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCListenEntries collection' storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCListenEntries.Add Method

Adds a new FPCListenEntry object to the collection.

Syntax

[ oFPCListenEntry>  = ] FPCListenEntries.Add( IP )

Parameters

IP
IP to listen on.

Return Value

oFPCListenEntry
Reference to the FPCListenEntry object.

Applies To

FPCListenEntries


FPCListenEntries.AllBasicAuthentication Property

Sets or retrieves the authentication access of the proxy.

Syntax

FPCListenEntries.AllBasicAuthentication [ = bAllBasicAuthentication ]

Possible Values

bAllBasicAuthentication
Boolean that specifies the authentication access of the proxy.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.AllDigestAuthentication Property

Sets or retrieves the authentication access of the proxy.

Syntax

FPCListenEntries.AllDigestAuthentication [ = bAllDigestAuthentication ]

Possible Values

bAllDigestAuthentication
Boolean that specifies the authentication access of the proxy.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.AllDomain Property

Sets or retrieves a string value that specifies the domain for authentication.

Syntax

FPCListenEntries.AllDomain [ = sDomain ]

Possible Values

sDomain
String that specifies the domain for authentication.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.AllIntegratedWindowsAuthentication Property

Sets or retrieves the authentication access of the proxy.

Syntax

FPCListenEntries.AllIntegratedWindowsAuthentication [ = bAllIntegratedWindowsAuthentication ]

Possible Values

bAllIntegratedWindowsAuthentication
Boolean that specifies the authentication access of the proxy.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.AllSSLCertificateAuthentication Property

Sets or retrieves how the proxy handles all certificate authentication.

Syntax

FPCListenEntries.AllSSLCertificateAuthentication [ = bAllSSLCertificateAuthentication ]

Possible Values

bAllSSLCertificateAuthentication
Boolean that specifies the authentication access of the proxy.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.AllSSLServerCertificate Property

Sets or retrieves an FPCSSLCertificate object that represents the client certificate to use when authenticating against the client.

Syntax

FPCListenEntries.AllSSLServerCertificate [ = oFPCSSLCertificate ]

Possible Values

oFPCSSLCertificate
Reference to an FPCSSLCertificate object.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.Count Property

Retrieves the number of FPCListenEntry objects in the collection.

Syntax

[ iCount = ] FPCListenEntries.Count

Possible Values

iCount
Integer value that specifies the number of filter objects.

The property is read-only.

Applies To

FPCListenEntries


FPCListenEntries.Description Property

Sets or returns the description of the collection of listen entries.

Syntax

FPCListenEntries.Descriptions [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the collection of listen entries.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.Item Method

Retrieves the given FPCListenEntry object from the collection.

Syntax

[ vItem = ] FPCListenEntries.Item( Index )

Parameters

Index
Required. One-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCListenEntry. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCListenEntries


FPCListenEntries.Refresh Method

Reads all the FPCListenEntry objects from persistent storage.

Syntax

FPCListenEntries.Refresh()

Applies To

FPCListenEntries


FPCListenEntries.Remove Method

Removes an FPCListenEntry object from the collection.

Syntax

FPCListenEntries.Remove( Index )

Parameters

Index
Required. One-based index of the object to remove.

Applies To

FPCListenEntries


FPCListenEntries.Save Method

Saves all FPCListenEntry objects in the collection to persistent storage.

Syntax

FPCListenEntries.Save()

Applies To

FPCListenEntries


FPCListenEntries.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCListenEntries collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCListenEntries.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCListenEntries

See Also

FPCListenEntry


FPCListenEntry Object

The FPCListenEntry object defines an IP and port on which the forward proxy or reverse proxy listens for incoming connections. These settings are manipulated with the IP property. The FPCServer.ForwardProxyListenEntries and FPCServer.ReverseProxyListenEntries properties are collections of FPCListenEntry objects.

The FPCListenEntry object is a member of the FPCListenEntries collection.

Note to C++ Programmers

This object implements the IFPCListenEntry interface.

Methods

The following table lists the methods of the FPCListenEntry object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.
Save | Saves the object's configuration information to persistent storage.

Properties

The following table lists the properties of the FPCListenEntry object.

Property | Description
BasicAuthentication | Sets or retrieves the authentication access of the proxy.
Description | Sets or returns the description of the entry.
DigestAuthentication | Sets or retrieves the authentication access of the proxy.
Domain | Sets or retrieves the domain for authentication.
IntegratedWindowsAuthentication | Sets or retrieves the authentication access of the proxy.
IP | Sets or retrieves the IP on which the proxy listens.
SSLCertificateAuthentication | Sets or retrieves how the proxy handles client certificates.
SSLServerCertificate | Sets or retrieves the client certificate used when authenticating against the client.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCListenEntry.BasicAuthentication Property

Sets or retrieves the authentication access of the proxy.

Syntax

FPCListenEntry.BasicAuthentication [ = bBasicAuthentication ]

Possible Values

bBasicAuthentication
Boolean value that specifies the authentication access of the proxy.

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.Description Property

Sets or returns the description of the entry.

Syntax

FPCListenEntry.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the entry.

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.DigestAuthentication Property

Sets or retrieves the authentication access of the proxy.

Syntax

FPCListenEntry.DigestAuthentication [ = bDigestAuthentication ]

Possible Values

bDigestAuthentication
Boolean value that specifies the authentication access of the proxy.

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.Domain Property

Sets or retrieves the domain for authentication.

Syntax

FPCListenEntry.Domain [ = sDomain ]

Possible Values

sDomain
String value that specifies the domain name.

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.IntegratedWindowsAuthentication Property

Sets or retrieves the authentication access of the proxy.

Syntax

FPCListenEntry.IntegratedWindowsAuthentication [ = bIntegratedWindowsAuthentication ]

Possible Values

bIntegratedWindowsAuthentication
Boolean value that specifies the authentication access of the proxy.

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.IP Property

Sets or retrieves the IP on which the proxy listens.

Syntax

FPCListenEntry.IP [ = Ip ]

Possible Values

Ip
IP string in x.y.z.t format

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.Refresh Method

Reads the object's configuration information from persistent storage, discarding any changes to the current configuration that were not saved.

Syntax

FPCListenEntry.Refresh()

Applies To

FPCListenEntry


FPCListenEntry.Save Method

Saves the object's configuration information to persistent storage.

Syntax

FPCListenEntry.Save()

Applies To

FPCListenEntry


FPCListenEntry.SSLCertificateAuthentication Property

Sets or retrieves how the proxy handles client certificates.

Syntax

FPCListenEntry.SSLCertificateAuthentication [ = bSSLCertificateAuthentication ]

Possible Values

bSSLCertificateAuthentication
Boolean value that specifies the authentication access of the proxy.

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.SSLServerCertificate Property

Sets or retrieves the client certificate used when authenticating against the client.

Syntax

FPCListenEntry.SSLServerCertificate [ = oFPCSSLCertificate ]

Possible Values

oFPCSSLCertificate
Reference to an FPCSSLCertificate object.

The property is read-write.

Applies To

FPCListenEntry


FPCLog Object

The FPCLog object is used to set the logging configuration of a specific component.

FPCLog is a member of the FPCLogs collection.

Note to C++ Programmers

This object implements the IFPCLog interface.

Methods

The following table lists the methods of the FPCLog object.

Method | Description
Refresh | Read the log configuration from persistent storage.
Save | Saves the log configuration to persistent storage.

Properties

The following table lists the properties of the FPCLog object.

Property | Description
ComponentType | Retrieves the type of the component to which this configuration belongs.
LogEnabled | Sets or retrieves a Boolean value that specifies whether logging is enabled.
LogFieldSelection | Sets or retrieves a bit field selection of logged columns.
LogFileDirectory | Sets or retrieves the directory containing the text log files.
LogFileDirectoryType | Sets or retrieves the type of the files logging directory.
LogFileKeepOld | Sets or retrieves an integer value that specifies the number of old log files to keep.
LogFilePeriod | Sets or retrieves the period of time before starting a new text log file.
LogFilesCompress | Sets or retrieves a Boolean value that specifies whether text log files are compressed.
LogSqlDataSource | Sets or retrieves the name of the structured query language (SQL) data source.
LogSqlPassword | Sets the password for the SQL table.
LogSqlTableName | Sets or retrieves the name of the SQL table.
LogSqlUserName | Sets or retrieves the user name of the SQL table.
LogType | Sets or retrieves the type of the logging method.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCLog.ComponentType Property

Retrieves the type of component to which this configuration belongs.

Syntax

[ LoggingComponents = ] FPCLog.ComponentType

Possible Values

LoggingComponents
A value from the FpcLoggingComponents enumeration.
The property is read-only.

Applies To

FPCLog


FPCLog.LogEnabled Property

Sets or retrieves a Boolean value that specifies whether logging is enabled.

Syntax

FPCLog.LogEnabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Logging is enabled.
FALSE | Logging is disabled.

The property is read-write.

Applies To

FPCLog


FPCLog.LogFieldSelection Property

Sets or retrieves a bit field selection of logged columns.

Syntax

FPCLog.LogFieldSelection[ = iSelection ]

Possible Values

iSelection
Bit field that specifies the logged columns.

The property is read-write.

Applies To

FPCLog


FPCLog.LogFileDirectory Property

Sets or retrieves the directory that contains the text log files.

Syntax

FPCLog.LogFileDirectory [ = sDir ]

Possible Values

sDir
String that specifies the directory.

The property is read-write.

Applies To

FPCLog


FPCLog.LogFileDirectoryType Property

Sets or retrieves the type of the files logging directory.

Syntax

FPCLog.LogFileDirectoryType [ = type ]

Possible Values

type
Value from the FpcLogFileDirectoryType enumeration. If the value fpcLogRelativePath is selected, this value is ignored.

The property is read-write.

Applies To

FPCLog


FPCLog.LogFileKeepOld Property

Sets or retrieves an integer value that specifies the number of old log files to keep.

Note Setting the value to 0 disables this property.

Syntax

FPCLog.LogFileKeepOld [ = iKeepOld ]

Possible Values

iKeepOld
Number of old files that are retained.

The property is read-write.

Applies To

FPCLog


FPCLog.LogFilePeriod Property

Sets or retrieves the period of time before starting a new text log file.

Syntax

FPCLog.LogFilePeriod [ = period ]

Possible Values

period
Value from the FpcLogPeriod enumeration.

The property is read-write.

Applies To

FPCLog


FPCLog.LogFilesCompress Property

Sets or retrieves a Boolean value that specifies whether text log files are compressed.

Note This feature is supported only when logging to partitions formatted using NTFS file systems.

Syntax

FPCLog.LogFilesCompress [ = bCompress ]

Possible Values

bCompress
A Boolean value that specifies whether text log files are compressed.

The property is read-write.

Applies To

FPCLog


FPCLog.LogSqlDataSource Property

Sets or retrieves the SQL database source name (DSN).

Syntax

FPCLog.LogSqlDataSource [ = sName ]

Possible Values

sName
String that specifies the SQL DSN.

The property is read-write.

Applies To

FPCLog


FPCLog.LogSqlPassword Property

Sets or retrieves the password for the SQL table.

Syntax

FPCLog.LogSqlPassword [ = sPassword ]

Possible Values

sPassword
String that specifies the password.

The property is write-only.

Applies To

FPCLog


FPCLog.LogSqlTableName Property

Sets or retrieves the name of the SQL table.

Syntax

FPCLog.LogSqlTableName [ = sName ]

Possible Values

sName
String that specifies the SQL table name.

The property is read-write.

Applies To

FPCLog


FPCLog.LogSqlUserName Property

Sets or retrieves the user name of the SQL table.

Syntax

FPCLog.LogSqlUserName [ = sName ]

Possible Values

sName
String that specifies the SQL table user name.

The property is read-write.

Applies To

FPCLog


FPCLog.LogType Property

Sets or retrieves the type of the logging method.

Syntax

FPCLog.LogType [ = type ]

Possible Values

type
An value from the FpcLogType enumeration.

The property is read-write.

Applies To

FPCLog


FPCLog.Refresh Method

Reads the log configuration from persistent storage.

Syntax

FPCLog.Refresh()

Applies To

FPCLog


FPCLog.Save Method

Saves the log configuration to persistent storage.

Syntax

FPCLog.Save()

Applies To

FPCLog


FPCLogs Collection

The FPCLogs collection is used to access the collection of FPCLog objects.

FPCLogs is a property of an FPCArray object.

Note to C++ Programmers

This collection implements the IFPCLogs interface.

Methods

The following table lists the methods of the FPCLogs collection.

Method | Description
Item | Retrieves the given FPCLog object from the collection.
Refresh | Reads all log's configuration from persistent storage, discarding any changes that were not saved.
Save | Saves the configuration of all logs to persistent storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCLogs.Item Method

Retrieves the given FPCLog object from the collection.

Syntax

[ vItem = ] FPCLogs.Item( LoggingComponents )

Parameters

LoggingComponents
A value from the FpcLoggingComponents enumeration.

Return Values

vItem
If successful, returns the FPCLog object specified by the LoggingComponents parameter. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCLogs


FPCLogs.Refresh Method

Reads all logs' configuration from persistent storage, discarding any changes that were not saved.

Syntax

FPCLogs.Refresh()

Applies To

FPCLogs


FPCLogs.Save Method

Saves the configuration of all logs to persistent storage.

Syntax

FPCLogs.Save()

Applies To

FPCLogs


FPCNetworkConfiguration Object

The FPCNetworkConfiguration object is used to access the network configuration. The most important information is accessed through the LAT and LDT properties of FPCNetworkConfiguration. Both properties return an object for manipulating either the Local Address Table (LAT) or Local Domain Table (LDT).

This object is a property of the FPCArray object.

Note to C++ Programmers

This object implements the IFPCNetworkConfiguration interface.

Methods

The following table lists the methods of the FPCNetworkConfiguration object.

Method | Description
Refresh | Reads the object from persistent storage, discarding any changes to the object that were not saved.
Save | Saves the configuration of FPCNetConfig to persistent storage.

Properties

The following table lists the properties of the FPCNetworkConfiguration object.

Property | Description
FirewallChaining | Retrieves an object that defines Firewall service chaining.
LAT | Returns a reference to an object for accessing the Local Address Table (LAT) configuration.
LDT | Returns a reference to an object for accessing the Local Domain Table (LDT) configuration.
RoutingRules | Retrieves a collection of all routing rules.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCNetworkConfiguration object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCNetworkConfiguration.FirewallChaining Property

Retrieves an object that defines Firewall service chaining.

Syntax

[ oFPCFirewallChaining = ] FPCNetConfig.FirewallChaining

Possible Values

oFPCFirewallChaining
Reference to the FPCFirewallChaining object.

The property is read-only.

Applies To

FPCNetworkConfiguration


FPCNetworkConfiguration.LAT Property

Returns a reference to an object for accessing the Local Address Table (LAT) configuration.

Syntax

[ collFPCLAT = ] FPCNetConfig.LAT

Possible Values

collFPCLAT
Reference to the FPCLAT collection.

The property is read-only.

Example

The following adds a new LAT entry to the FPCLAT collection.

Set objFPC  = CreateObject ("FPC.Root")
Set objNetConfig = objFPC.Arrays(1).NetworkConfiguration
Set objLAT = objNetConfig.LAT
ObjLAT.Add "2.2.2.2","3.3.3.3"
ObjLAT.Save

Applies To

FPCNetworkConfiguration

See Also

FPCLATEntry


FPCNetworkConfiguration.LDT Property

Returns a reference to an object for accessing the Local Domain Table (LDT) configuration.

Syntax

[ collFPCLDT = ] FPCNetConfig.LDT

Possible Values

collFPCLDT
Reference to the FPCLDT collection.

The property is read-only.

Applies To

FPCNetworkConfiguration


FPCNetworkConfiguration.Refresh Method

Reads the object from persistent storage, discarding any changes to the object that were not saved.

Syntax

FPCNetConfig.Refresh()

Applies To

FPCNetworkConfiguration


FPCNetworkConfiguration.RoutingRules Property

Retrieves a collection of all routing rules.

Syntax

[ collFPCRoutingRules = ] FPCNetConfig.RoutingRules

Possible Values

collFPCRoutingRules
Reference to the FPCRoutingRules collection.

Applies To

FPCNetworkConfiguration

See Also

FPCRoutingRule


FPCNetworkConfiguration.Save Method

Saves the object's configuration to persistent storage.

Syntax

FPCNetConfig.Save()

Applies To

FPCNetworkConfiguration


FPCNetworkConfiguration.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the object's storage. This property allows third-party extensions to be integrated into ISA.

Syntax

[ collFPCVendorParametersSets = ] FPCNetConfig.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCNetworkConfiguration


FPCPNATServerMapping Object

Secure Network Address Translation (SecureNAT) substitutes a global IP address, which is valid on the Internet, for an internal IP address. The FPCPNATServerMapping object describes a SecureNAT mapping of an external Internet Protocol (IP) and a port slot on an ISA computer to an internal IP. Requests received on the external IP will be redirected to the internal IP. Such mapping is used to publish internal servers — for example, a mail server — to the outer network This mapping is protocol based. Therefore, only requests that are identified as part of the designated protocol will be redirected to the internal server.

This object is a member of the FPCPNATServerMappings collection.

Note to C++ Programmers

This collection implements the IFPCPNATServerMapping interface.

Methods

The following table lists the methods of the FPCPNATServerMapping object.

Method | Description
GetPrimaryPortOfProtocolUsed | Returns the primary port associated with the protocol that was set in the call to the SetProtocol method.
Refresh | Reads the object's data from persistent storage, discarding any changes that were not saved.
Save | Saves the object's data to persistent storage.
SetProtocol | Sets the protocol for which the mapping will be done.

Properties

The following table lists the properties of the FPCPNATServerMapping object.

Property | Description
AppliesToMethod | Sets or retrieves the entity to which the mapping applies.
ClientAddressSetsExcluded | Retrieves the excluded client address sets.
ClientAddressSetsUsed | Retrieves the client address sets used.
Description | Sets or returns the description of the mapping.
Enabled | Sets or retrieves whether the rule is enabled.
ExternalIp | Defines the external address to which the specified internal addresses are mapped.
InternalIp | The internal address to which the requests on the external IP will be redirected.
Name | Sets or returns the name of the mapping.
ProtocolUsed | Specifies the protocol for which the internal-to-external mapping will be done.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCPNATServerMapping object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCPNATServerMapping.AppliesToMethod Property

Sets or retrieves the method used for deciding on the applicability of SecureNAT mapping.

Syntax

FPCPNATServerMapping.AppliesToMethod [ = AppliesToType]

Possible Values

AppliesToType
Applicability method. It can have a value from the FpcAppliesToType enumeration type.

The property is read-write.

Applies To

FPCPNATServerMapping


FPCPNATServerMapping.ClientAddressSetsUsed Property

Retrieves the client address sets used in the mapping.

Syntax

[ collFPCRefs = ] FPCPNATServerMapping.ClientAddressSetsUsed

Possible Values

collFPCRefs
The FPCRefs collection used to define the client address sets.

The property is read-write.

Applies To

FPCPNATServerMapping


FPCPNATServerMapping.ClientAddressSetsExcluded Property

Retrieves the client address sets excluded from the mapping.

Syntax

[ collFPCRefs = ] FPCPNATServerMapping.ClientAddressSetsExcluded

Possible Values

collFPCRefs
The FPCRefs collection used to define the client address sets.

The property is read-write.

Applies To

FPCPNATServerMapping


FPCPNATServerMapping.Description Property

Sets or retrieves the description of the mapping. The description is stored as a string.

Syntax

FPCPNATServerMapping.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the mapping.

The property is read-write.

Applies To

FPCPNATServerMapping


FPCPNATServerMapping.Enabled Property

Sets or retrieves whether the rule is enabled.

Syntax

FPCPNATServerMapping.Enabled [ = bEnabled ]

Possible Values

bEnabled
A Boolean value that has either of these settings:
Setting | Meaning
TRUE | Rule is enabled.
FALSE | Rule is disabled.

The property is read-write.

Applies To

FPCPNATServerMapping


FPCPNATServerMapping.ExternalIp Property

Sets or retrieves the external Internet Protocol (IP) address of one of the ISA servers in the array, to which the specified internal addresses are mapped. An external address is one that is not in the Local Address Table (LAT).

Syntax

FPCPNATServerMapping.ExternalIp [ = sExternalIP ]

Possible Values

sExternalIP
String that specifies the external IP.

The property is read-write.

Applies To

FPCPNATServerMapping


FPCPNATServerMapping.GetPrimaryPortOfProtocolUsed Method

Returns the primary port associated with the protocol that was set in the call to SetProtocol.

Syntax

[ iPort = ] FPCPNATServerMapping.GetPrimaryPortOfProtocolUsed

Possible Values

iPort
Integer that specifies the port number.

See Also

FPCPNATServerMapping


FPCPNATServerMapping.InternalIp Property

Sets or retrieves the internal IP address to which to map. This would be the address of the internal server you want to publish.

Syntax

FPCPNATServerMapping.InternalIp [ = sInternalIp ]

Possible Values

sInternalIp
String that specifies the internal IP.

The property is read-write.

Applies To

FPCPNATServerMapping


FPCPNATServerMapping.Name Property

Sets or retrieves the name of the rule. The name of the rule is stored as a string.

Syntax

FPCPNATServerMapping.Name [ = sName ]

Possible Values

sName
String that specifies the rule name.

The property is read-write.

Applies To

FPCPNATServerMapping


FPCPNATServerMapping.ProtocolUsed Property

Retrieves a FPCRef object that represents the protocol for which the server mapping is done.

Syntax

[ oFPCRef = ] FPCPNATServerMapping.ProtocolUsed.

Possible Values

oFPCRef
An FPCRef object that specifies the protocol.

The property is read-only.

Applies To

FPCPNATServerMapping


FPCPNATServerMapping.Refresh Method

Reads the filter's private data from persistent storage.

Syntax

FPCPNATServerMapping.Refresh()

Applies To

FPCPNATServerMapping


FPCPNATServerMapping.Save Method

Saves the filter's private data to persistent storage.

Syntax

FPCPNATServerMapping.Save()

Applies To

FPCPNATServerMapping


FPCPNATServerMapping.SetProtocol Method

Sets the protocol for which the mapping is done. Note that in order for the operation to succeed, the protocol must be a server protocol, which has an inbound primary connection.

Syntax

FPCPNATServerMapping.SetProtocol( sProtocolName, sPluginGuid, FpcItemScope )

Parameters

sProtocolName
Required. String that specifies the name of the protocol.
sPluginGuid
Optional. String that specifies the GUID of the plug-in if this is a plug-in protocol.
FpcItemScope
Optional. Value from the FpcItemScope enumeration. Specifies whether the protocol is taken from the enterprise list of protocols or the local array list of protocols.

Applies To

FPCRefs

See Also

FPCRef


FPCPNATServerMapping.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCPNATServerMapping object's storage.

Syntax

[ colFPCVendorParametersSets = ] FPCPNATServerMapping.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCPNATServerMapping


FPCPNATServerMappings Collection

The FPCPNATServerMappings collection provides access to a group of FPCPNATServerMapping objects. This object is a property of the FPCPublishing object.

Note to C++ Programmers

This collection implements the IFPCPNATServerMappings interface.

Methods

The following table lists the methods of the FPCPNATServerMappings collection.

Method | Description
Add | Creates a new FPCPNATServerMapping object.
Item | Retrieves the given object from the collection.
Refresh | Reads all the objects from persistent storage, discarding any changes to the current changes that were not saved.
Remove | Removes an FPCPNATServerMapping object from the collection.
Save | Saves all the items in the collection to persistent storage.

Properties

The following table lists the properties of the FPCPNATServerMapping collection.

Property | Description
Count | Retrieves the number of objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCPNATServerMappings.Add Method

Creates a new FPCPNATServerMapping object in the collection and returns a reference to it.

Syntax

[ oFPCPNATServerMapping = ] FPCPNATServerMappings.Add( sName )

Parameters

sName
String that specifies the new FPCPNATServerMapping object to add.

Return Values

oFPCPNATServerMapping
Returns a reference to the new FPCPNATServerMapping object.

Applies To

FPCPNATServerMappings


FPCPNATServerMappings.Count Property

Retrieves the number of content groups objects in the collection.

Syntax

[ iCount = ] FPCPNATServerMappings.Count

Possible Values

iCount
Integer value that specifies the number of destination set objects.

The property is read-only.

Applies To

FPCPNATServerMappings


FPCPNATServerMappings.Item Method

Retrieves the given FPCPNATServerMapping object from the collection.

Syntax

[ vItem = ] FPCPNATServerMappings.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
Variant. Returns an object if successful; otherwise NULL .

Applies To

FPCPNATServerMappings


FPCPNATServerMappings.Refresh Method

Reads all the items from persistent storage, discarding any changes that were not saved.

Syntax

FPCPNATServerMappings.Refresh()

Applies To

FPCPNATServerMappings


FPCPNATServerMappings.Remove Method

Removes a content group set object from the collection.

Syntax

FPCPNATServerMappings.Remove( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to remove.

Applies To

FPCPNATServerMappings


FPCPNATServerMappings.Save Method

Saves all the items in the collection to persistent storage.

Syntax

FPCPNATServerMappings.Save()

Applies To

FPCPNATServerMappings


FPCPNATServerMappings.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCPNATServerMappings collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCPNATServerMappings.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCPNATServerMappings


FPCPolicyElements Object

The FPCPolicyElements object is used to access configuration settings of ISA, including schedules, bandwidth priorities, destination sets, client address sets, and protocol definitions. The properties of the FPCPolicyElements object are closely mirrored by what is shown under the Policy Elements node of the ISA administration tool. Configuration settings of each of these categories are programmatically managed through the FPCPolicyElements object.

This object is a property of the FPCArray object.

Note to C++ Programmers

This object implements the IFPCPolicyElements interface.

Methods

The following table lists the methods of the FPCPolicyElements object.

Method | Description
Refresh | Reads the object from persistent storage, discarding any changes to the object that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCPolicyElements object.

Property | Description
BandwidthPriorities | Returns the collection of bandwidth priorities in this domain array.
ClientAddressSets | Returns a collection of all client address sets in this domain array.
ContentGroups | Returns a collection of all content groups in this domain array.
DestinationSets | Returns a collection of all destination sets in this domain array.
DialupEntries | Returns a collection of dialup entries.
EventDefinitions | Returns a collection of all alert events in this domain array.
ProtocolDefinitions | Returns a collection for accessing the Firewall service protocols.
Schedules | Returns a collection of all schedules in this domain array.
VendorParametersSets | Returns a reference to an object for storing and loading custom data into the FPCPolicyElements object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCPolicyElements.BandwidthPriorities Property

Returns the collection of bandwidth priorities in this domain array. Bandwidth classes can be added and removed with the Add and Remove methods of the FPCBandwidthPriorities collection.

Syntax

[ collFPCBandwidthPriorities = ] FPCPolicyElements.BandwidthPrioritiess

Possible Values

collFPCBandwidthPriorities
Reference to the FPCBandwidthPriorities collection.

Applies To

FPCPolicyElements


FPCPolicyElements.ClientAddressSets Property

Returns a collection of all client address sets in this domain array. Client sets can be added and removed with the Add and Remove methods of the FPCClientAddressSets collection.

Syntax

[ collFPCClientAddressSets = ] FPCPolicyElements.ClientAddressSets

Possible Values

colFPCClientAddressSets
Reference to an FPCClientAddressSets collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.ContentGroups Property

Returns a collection of all content groups in this domain array. The FPCContentGroups collection that is returned can be used to programmatically update content groups.

Syntax

[ collFPCContentGroups = ] FPCPolicyElements.ContentGroups

Possible Values

collFPCContentGroups
Reference to an FPCContentGroups collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.DestinationSets Property

Returns a collection of all destination sets in this domain array. You can use the FPCDestinationSets collection that is returned to programmatically update destination sets. Automating the task of updating destination sets can save time for a system administrator using ISA. For an example of a script to perform this task see Configuring Destination Sets.

Syntax

[ collFPCDestinationSets = ] FPCPolicyElements.DestinationSets

Possible Values

collFPCDestinationSets
Reference to the FPCDestinationSets collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.DialupEntries Property

Returns a collection of all dialup entries in this domain array. You can use the FPCDestinationSets collection that is returned to update destination sets programmatically. Automating the task of updating destination sets can save time for a system administrator who uses ISA. For an example of a script to perform this task see Configuring Destination Sets.

Syntax

[ collFPCDestinationSets = ] FPCPolicyElements.DestinationSets

Possible Values

collFPCDestinationSets
Reference to the FPCDestinationSets collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.EventDefinitions Property

Returns a reference to a FPCEventDefinitions collection. Events can be added and removed with the Add and Remove methods of the collection.

Syntax

[ collFPCEventDefinitions = ] FPCPolicyElements.EventDefinitions

Possible Values

collFPCEventDefinitions
Reference to an FPCEventDefinitions collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.ProtocolDefinitions Property

Returns a reference to an FPCProtocolDefinitions collection. This collection is used to access the Firewall service protocols. Firewall service protocols can be added and removed with the Add and Remove methods of the FPCProtocolDefinitions collection.

Syntax

[ collFPCProtocolDefinitions = ] FPCPolicyElements.ProtocolDefinitions

Possible Values

collFPCProtocolDefinitions
Reference to an FPCProtocolDefinitions collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.Refresh Method

Reads the object from persistent storage, discarding any changes to the object that were not saved.

Syntax

FPCPolicyElements.Refresh()

Applies To

FPCPolicyElements


FPCPolicyElements.Save Method

Saves the object's configuration to persistent storage. It is important to remember that any changes made in scripts and programs will not be saved unless the Save method is called.

Syntax

FPCPolicyElements.Save()

Applies To

FPCPolicyElements


FPCPolicyElements.Schedules Property

Returns a collection of all schedules in this domain array. ISA schedules are defined by hour blocks defined within each day of the week, and are accessed by means of the FPCSchedule object.

See Configuring Schedules for an example of using the FPCSchedules collection.

Syntax

[ collFPCSchedules = ] FPCPolicyElements.Schedules

Possible Values

collFPCSchedules
Reference to an FPCSchedules collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCPolicyElements object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCPolicyElements.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to an FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCPolicyElements


FPCPrimaryRoute Object

The FPCPrimaryRoute object represents the primary route entity, either a single ISA server or a domain array of ISA servers. This object is a property of the FPCRoutingRule object, which you can access through the FPCRoutingRule.PrimaryRoute property.

Note to C++ Programmers

This object implements the IFPCPrimaryRoute interface.

Methods

The following table lists the methods of the FPCPrimaryRoute object.

Method | Description
Refresh | Reads the object's information from persistent storage.
Save | Saves the object's configuration to persistent storage.
SetAutoPollConfig | Sets whether proxy polling of the upstream proxy server or domain array for membership information is enabled.
SetRedirectUrl | Sets the action to Redirect and sets the redirect URL and its code page.
SetServerAndPort | Sets the server and port for the entity.

Properties

The following table lists the properties of the FPCPrimaryRoute object.

Property | Description
AuthenticationEnabled | Sets or retrieves whether use of authentication in upstream routing is enabled.
AuthenticationType | Sets or retrieves the type of authentication that the entity uses.
AutoDialOut | Retrieves a refrence to an FPCAutoDial object that represents the automatic-dial settings.
AutomaticPollConfig | Retrieves whether proxy polling of the upstream proxy or domain array for membership information is enabled.
BackupRoute | Retrieves a reference to an object that represents the specific proxy or domain array of the secondary (backup) route.
Credentials | Retrieves an FPCCredentials object used to read and write credentials information. This information will be used if a proxy server needs to authenticate with an upstream proxy server.
PollAtUrl | Sets or retrieves the URL, usually at the upstream proxy, at which to poll for the domain array configuration information. This property if valid if the AutomaticPollConfig property is enabled.
PollAtUrlCpid | Retrieves the code page ID (Cpid) of a URL.
RedirectUrl | Sets or retrieves the URL to redirect requests if the Action property is set to the enumeration FpcPrimaryRouteType.
RedirectUrlCpid | Retrieves the redirect code page ID (Cpid) of a URL.
RouteServerName | Retrieves the name of the proxy or domain array.
RouteServerPort | Retrieves the port that this entity is listening on.
RouteServerSSLPort | Sets or retrieves the port for listening on a secure channel.
RouteType | Sets or retrieves the primary route type.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCPrimaryRoute.AuthenticationEnabled Property

Sets or retrieves whether use of authentication in upstream routing is enabled.

Syntax

FPCPrimaryRoute.AuthenticationEnabled [= bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Authentication is enabled.
FALSE | Authentication is disabled.

The property is read-write.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.AuthenticationType Property

Sets or retrieves the type of authentication that the entity uses.

Syntax

FPCPrimaryRoute.AuthenticationType [ = AuthType ]

Possible Values

AuthType
Authentication type. It can have a value from the FpcAuthType enumeration.

The property is read-write.

Remarks

Basic authentication (fpcUiAuthBasic) is not encrypted.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.AutoDialOut Property

Retrieves a reference to an FPCAutoDial object that represents the automatic-dial settings.

Syntax

[ oFPCAutoDial = ] FPCPrimaryRoute.AutoDialOut

Possible Values

oFPCAutoDial
Reference to an FPCAutoDial object that represents the automatic-dial settings.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.AutomaticPollConfig Property

Retrieves whether proxy polling of the upstream proxy or domain array is enabled for membership information.

Syntax

FPCPrimaryRoute.AutomaticPollConfig [ = bEnabled ]

Possible Values

bEnabled
A Boolean value that has either of these settings:
Setting | Meaning
TRUE | Proxy polling is enabled.
FALSE | Proxy polling is disabled.

The property is read only. It can be modified through the SetAutoPollConfig method.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.BackupRoute Property

Retrieves a reference to an object that represents the specific proxy or array of the secondary (backup) route.

Syntax

[ oFPCBackupRoute = ] FPCPrimaryRoute.BackupRoute

Possible Values

oFPCBackupRoute
Reference to the FPCBackupRoute object.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.Credentials Property

Retrieves an FPCCredentials object to read and write credential information. A ISA Server computer will use this information if it needs to authenticate a connection to an upstream proxy server.

Syntax

[ oFPCCredentials = ] FPCPrimaryRoute.Credentials

Possible Values

oFPCCredentials
Reference to an FPCCredentials object.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.PollAtUrl Property

Sets or retrieves the URL, usually at the upstream proxy, to poll for the domain array configuration information. This property is valid if the AutomaticPollConfig property is enabled.

Syntax

FPCPrimaryRoute.PollAtURL [ = sURL ]

Possible Values

sURL
String that specifies the URL.

The property is read-write.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.PollAtUrlCpid Property

Retrieves the code page ID (Cpid) of a URL. The code page ID is useful if a URL string contains national characters that are not ANSI standard; for example, if a URL string contains Japanese characters.

Syntax

[ lCpid = ] FPCPrimaryRoute.PollAtUrlCpid

Return Value

lCpid
Long that specifies the Cpid of a URL.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.RedirectUrl Property

Retrieves the URL to redirect requests to if the RouteType property is set to fpcPrimaryRouteAlternate.

Syntax

FPCPrimaryRoute.RedirectURL [ = sURL ]

Possible Values

sURL
String that specifies the URL.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.RedirectUrlCpid Property

Retrieves the redirect URL code-page identifier (Cpid) if the RouteType property is set to fpcPrimaryRouteAlternate. The Cpid is useful if a URL string contains national characters that are not ANSI standard; for example, if a URL string contains Japanese characters.

Syntax

FPCPrimaryRoute.RedirectURLCpid [ = lCpid ]

Possible Values

lCpid
Long value that specifies the Cpid.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.Refresh Method

Reads the object's information from persistent storage.

Syntax

FPCPrimaryRoute.Refresh()

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.RouteServerName Property

Retrieves the name of the proxy or domain array.

Syntax

[ sName = ] FPCPrimaryRoute.RouteServerName

Possible Values

sName
String that specifies the name of the proxy or domain array.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.RouteServerPort Property

Retrieves the port on which this entity is listening.

Syntax

[ lPort = ] FPCPrimaryRoute.RouteServerPort

Possible Values

lPort
Long value that specifies the port number. It can be a value from 1 to 65535.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.RouteServerSSLPort Property

Sets or retrieves the port for listening on a secure channel. In the ISA Server administration tool, this property is represented on the Redirection tab of each routing rule Properties dialog box.

Syntax

[ lSSLPort = ] FPCPrimaryRoute.RouteServerSSLPort

Possible Values

lSSLPort
Long value that specifies the port number. It can be a value from 1 to 65535.

The property is read-write.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.RouteType Property

Sets or retrieves the primary route type.

Syntax

[ RouteType = ] FPCPrimaryRoute.RouteType

Possible Values

RouteType
Routing type. It can have a value from the FpcPrimaryRouteType enumeration.

The property is read-write.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.Save Method

Saves the object's configuration to persistent storage.

Syntax

FPCPrimaryRoute.Save()

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.SetAutoPollConfig Method

Sets whether proxy polling of the upstream proxy or domain array is enabled for membership information.

Syntax

FPCPrimaryRoute.SetAutoPollConfig(fSetAuto, sAutoPollUrl, lCpidUrl)

Parameters

fSetAuto
A Boolean expression that specifies whether automatic configuration is to be enabled.
sAutoPollUrl
An optional string that specifies the URL, usually at the upstream proxy, to poll for the domain array configuration information. If fSetAuto is set to TRUE, this parameter must hold a valid URL; otherwise, sAutoPollUrl is ignored.
lCpidUrl
An optional long value that specifies the code page for the URL.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.SetRedirectUrl Method

Sets the redirect URL and its code page identifier (Cpid).The Cpid is useful if a URL string contains national characters that are not ANSI standard; for example, if a URL string contains Japanese characters.

Syntax

FPCPrimaryRoute.SetRedirectUrl( sUrl, lRedirectUrlCpid )

Parameters

sUrl
Required. String that specifies the redirect URL.
lRedirectUrlCpid
Optional. Long value that specifies the CPID of the redirect URL.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.SetServerAndPort Method

Sets the server and port for the entity.

Syntax

FPCPrimaryRoute.SetServerAndPort( sServerName, lPort )

Parameters

sServerName
String that specifies the name of the server.
lPort
Long value that specifies the port number that the server listens on. It can be a value from 1 to 65535.

Applies To

FPCPrimaryRoute


FPCProtocolConnection Object

The FPCProtocolConnection object represents a single connection in a single Firewall service protocol. This object is a member of the FPCProtocolConnections collection.

Note to C++ Programmers

This object implements the IFPCProtocolConnection interface.

Methods

The following table lists the methods of the FPCProtocolConnection object.

Method | Description
Refresh | Reads the cache configuration from persistent storage, discarding any changes to it that were not saved.
Save | Saves the connection configuration to persistent storage.
Set | Sets all of the parameters of this connection.

Properties

The following table lists the properties of the FPCProtocolConnection object.

Property | Description
Direction | Retrieves the direction of the connection.
PortHigh | Retrieves a port number designating the end of the range.
PortLow | Retrieves a port number designating the beginning of the range.
Protocol | Retrieves the communication protocol of the connection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCProtocolConnection object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProtocolConnection.Direction Property

Retrieves the direction of the connection.

Syntax

[ sDirection = ] FPCProtocolConnection.Direction

Possible Values

sDirection
String that specifies the connection direction. It can have a value from the FpcConnectionDirectionType enumeration.

The property is read-only.

Applies To

FPCProtocolConnection


FPCProtocolConnection.PortHigh Property

Retrieves a port number designating the end of the range.

Syntax

[ iPort = ] FPCProtocolConnection.PortHigh

Possible Values

iPort
Integer value that specifies the ending port number. It can be a value from 1 through 65535.

The property is read-only.

Remarks

This value can be equal to the PortLow property to indicate that there is only one port, not a range of ports.

Applies To

FPCProtocolConnection


FPCProtocolConnection.PortLow Property

Retrieves a port number designating the beginning of the range.

Syntax

[ iPort = ] FPCProtocolConnection.PortLow

Possible Values

iPort
Integer value that specifies the beginning port number. It can be a value from 1 through 65535.

The property is read-only.

Applies To

FPCProtocolConnection


FPCProtocolConnection.Protocol Property

Retrieves the communication protocol of the connection.

Syntax

[ ConnectionProtocolType = ] FPCProtocolConnection.Protocol

Possible Values

ConnectionProtocolType
Communication protocol used in the connection. It can have a value of the FpcConnectionProtocolType enumeration.

The property is read-only.

Applies To

FPCProtocolConnection


FPCProtocolConnection.Refresh Method

Reads the object configuration from persistent storage, discarding any changes to it that were not saved.

Syntax

FPCProtocolConnection.Refresh()

Applies To

FPCProtocolConnection


FPCProtocolConnection.Save Method

Saves the connection configuration to persistent storage.

Syntax

FPCProtocolConnection.Save()

Applies To

FPCProtocolConnection


FPCProtocolConnection.Set Method

Sets all of the parameters of this connection.

Syntax

FPCProtocolConnection.Set(iPortLo, iPortHi, Protocol, Direction)

Parameters

iPortLo
Integer value that specifies the beginning port number. It can be a value from 1 through 65535.
iPortHi
Integer value that specifies the ending port number. It can be a value from 1 through 65535, and must be equal to or greater than the value of the iPortLo parameter.
Protocol
Required. Protocol used in the connection. It can have a value from the FpcConnectionProtocolType enumeration.
Direction
Required. Connection direction. It can have a value from the FpcConnectionDirectionType enumeration.

Applies To

FPCProtocolConnection


FPCProtocolConnection.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCProtocolConnection object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCProtocolConnection.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCProtocolConnection


FPCProtocolConnections Collection

The FPCProtocolConnections collection retrieves a group of all FPCProtocolConnection objects of a single protocol.

The FPCProtocolConnections collection is a property of the FPCProtocolDefinition object.

Note to C++ Programmers

This collection implements the IFPCProtocolConnections interface.

Methods

The following table lists the methods of the FPCProtocolConnections collection.

Method | Description
Add | Creates a new connection object and returns a reference to it.
Item | Retrieves the given FPCProtocolConnection object from the collection.
Refresh | Reads all the connections from persistent storage, discarding any changes to the current connections that were not saved.
Remove | Removes the given object from the collection.
Save | Saves all the connections in the collection to persistent storage.

Properties

The following table lists the properties of the FPCProtocolConnections collection.

Property | Description
Count | Retrieves the number of secondary connection objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCProtocolConnections collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProtocolConnections.Add Method

Creates a new connection object and returns a reference to it.

Syntax

[ oFPCProtocolConnection = ] FPCProtocolConnections.Add( Direction, Protocol, iPortLow, iPortHigh )

Parameters

Direction
Required. Connection direction. It can have a value from the FpcConnectionDirectionType enumeration.
Protocol
Required. Protocol used in the connection. It can have a value of the FpcConnectionProtocolType enumeration.
iPortLow
Lower bound of the port range used in the connection.
iPortHigh
Higher bound of the port range used in the connection.

Return Value

Variant. Returns a reference to the new FPCProtocolConnection object if successful; NULL otherwise.

Applies To

FPCProtocolConnections


FPCProtocolConnections.Count Property

Retrieves the number of secondary connection objects in the collection.

Syntax

[ iCount = ] FPCProtocolConnections.Count

Possible Values

iCount
Integer value that specifies the number of secondary connection objects.

The property is read-only.

Applies To

FPCProtocolConnections


FPCProtocolConnections.Item Method

Retrieves the given FPCProtocolConnection object from the collection.

Syntax

[ vItem = ] FPCProtocolConnections.Item( vIndex )

Parameters

vIndex
Required. Number that specifies the one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCProtocolConnection. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCProtocolConnections


FPCProtocolConnections.Refresh Method

Reads all the connections from persistent storage, discarding any changes to the current connections that were not saved.

Syntax

FPCProtocolConnections.Refresh()

Applies To

FPCProtocolConnections


FPCProtocolConnections.Remove Method

Removes the given object from the collection.

Syntax

FPCProtocolConnections.Remove( iIndex )

Parameters

iIndex
Required. One-based index of the object to remove.

Applies To

FPCProtocolConnections

See Also

FPCProtocolConnection


FPCProtocolConnections.Save Method

Saves all the connections in the collection to persistent storage.

Syntax

FPCProtocolConnections.Save()

Applies To

FPCProtocolConnections


FPCProtocolConnections.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCProtocolConnections collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCProtocolConnections.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Note to C++ Programmers

This property implements the IFPCProtocolConnections::VendorParametersSets property, with the following syntax:

HRESULT get_VendorParametersSets( IFPCVendorParametersSets *pVal);

Applies To

FPCProtocolConnections


FPCProtocolDefinition Object

The FPCProtocolDefinition object represents a single Firewall service protocol. A Firewall service protocol is supported by the Firewall service.

The FPCProtocolDefinition object is a member of the FPCProtocolDefinitions collection.

Note to C++ Programmers

This object implements the IFPCProtocolDefinition interface.

Methods

The following table lists the methods of the FPCProtocolDefinition object.

Method | Description
Refresh | Reads the protocol definition from persistent storage, discarding any changes to the current protocol settings that were not saved.
Save | Saves the protocol definition to persistent storage.
SetInitialConnection | Sets all the parameters for the initial (primary) connection for this protocol.

Properties

The following table lists the properties of the FPCProtocolDefinition object.

Property | Description
Description | Sets or retrieves the description of the protocol.
InitialConnectionDirection | Retrieves the direction of the initial (primary) connection.
InitialConnectionPort | Retrieves the port of the initial (primary) connection.
InitialConnectionProtocol | Retrieves the protocol of the initial (primary) connection.
Name | Sets or retrieves the name of the protocol.
SecondaryConnections | Retrieves a collection of all of this protocol's secondary connections.
SystemProtocol | Returns a Boolean value that specifies whether the protocol is a system protocol.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCProtocolDefinition object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProtocolDefinition.Description Property

Sets or retrieves the description of the protocol.

Syntax

FPCProtocolDefinition.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the protocol.

The property is read-write.

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.InitialConnectionDirection Property

Retrieves the direction of the initial (primary) connection.

Syntax

[ Direction = ] FPCProtocolDefinition.InitialConnectionDirection

Possible Values

Direction
Value that specifies the connection direction. It can have a value from the FpcConnectionDirectionType enumeration.

The property is read-only.

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.InitialConnectionPort Property

Retrieves the port of the initial (primary) connection.

Syntax

[ iPort = ] FPCProtocolDefinition.InitialConnectionPort

Possible Values

iPort
Integer value that specifies the port. It is a value from 1 through 65535.

The property is read-only.

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.InitialConnectionProtocol Property

Retrieves the protocol of the initial (primary) connection.

Syntax

[ Protocol = ] FPCProtocolDefinition.InitialConnectionProtocol

Possible Values

Protocol
Protocol used in the connection. It can have a value from the FpcConnectionProtocolType enumeration.

The property is read-only.

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.Name Property

Sets or retrieves the name of the protocol.

Syntax

FPCProtocolDefinition.Name [ = sName ]

Possible Values

sName
String that specifies the name of the protocol.

The property is read-write.

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.Refresh Method

Reads the protocol definition from persistent storage, discarding any changes to the current protocol settings that were not saved.

Syntax

FPCProtocolDefinition.Refresh()

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.Save Method

Saves the protocol definition to persistent storage.

Syntax

FPCProtocolDefinition.Save()

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.SecondaryConnections Property

Retrieves a collection of all of this protocol's secondary connections.

Syntax

[ collFPCProtocolConnections = ] FPCProtocolDefinition.SecondaryConnections

Possible Values

collFPCProtocolConnections
Reference to the FPCProtocolConnections collection.

The property is read-only.

Applies To

FPCProtocolDefinition

See Also

FPCProtocolConnection


FPCProtocolDefinition.SetInitialConnection Method

Sets all the parameters for the initial (primary) connection for this protocol.

Syntax

FPCProtocolDefinition.SetInitialConnection( Direction, Protocol, iPort )

Parameters

Direction
Required. Connection direction. It can have a value from the FpcConnectionDirectionType enumeration.
Protocol
Required. Protocol used in the connection. It can have a value from the FpcConnectionProtocolType enumeration.
iPort
Integer value in the range 1 through 65535.

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.SystemProtocol Property

Returns a Boolean value that specifies whether the protocol is a system protocol.

Syntax

[ bSystemProtocol = ] FPCProtocolDefinition.SystemProtocol

Possible Values

bSystemProtocol
Boolean value that specifies whether the protocol is a system protocol.

The property is read-only.

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCProtocolDefinition object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCProtocolDefinition.VendorParametersSets

Possible Values

collFPCtVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCProtocolDefinition


FPCProtocolDefinitions Collection

The FPCProtocolDefinitions collection provides access to all the Firewall service protocols in an ISA domain array. It gives access to the collection of FPCProtocolDefinition objects.

This collection is a property of the FPCPolicyElements object.

Note to C++ Programmers

This collection implements the IFPCProtocolDefinitions interface.

Methods

The following table lists the methods of the FPCProtocolDefinitions collection.

Method | Description
Add | Creates a new protocol object and returns a reference to it.
Item | Retrieves the given FPCProtocolDefinition object from the collection.
Refresh | Reads all the protocols from persistent storage, discarding any changes to the current protocols that were not saved.
Remove | Removes the given object from the collection.
Save | Saves all protocols in the collection to persistent storage.

Properties

The following table lists the properties of the FPCProtocolDefinitions collection.

Property | Description
Count | Retrieves the number of protocol objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCProtocolDefinitions collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProtocolDefinitions.Add Method

Creates a new protocol object and returns a reference to it.

Syntax

[ oFPCProtocolDefinition = ] FPCProtocolDefinitions.Add( sName,InitialConnectionDirection,InitialConnectionType,InitialConnectionPort )

Parameters

sName
Required. String that specifies the name of the new protocol object.
InitialConnectionDirection
The direction of the initial connection associated with the protocol. Can have a value from the FpcConnectionDirectionType enumeration.
InitialConnectionType
The IP type of the initial connection associated with the protocol. Can have a value from the FpcConnectionProtocolType enumeration.
InitialConnectionPort
The port for the initial connection associated with the protocol. Can be any value between 1 and 65536.

Return Value

oFPCProtocolDefinition
Returns a reference to an FPCProtocolDefinition object.

Applies To

FPCProtocolDefinitions


FPCProtocolDefinitions.Count Property

Retrieves the number of protocol objects in the collection.

Syntax

[ iCount = ] FPCProtocolDefinitions.Count

Possible Values

iCount
Integer value that specifies the number of protocol objects.

The property is read-only.

Applies To

FPCProtocolDefinitions

See Also

FPCProtocolDefinition


FPCProtocolDefinitions.Item Method

Retrieves the given FPCProtocolDefinition object from the collection.

Syntax

[ vItem = ] FPCProtocolDefinitions.Item( vIndex )

Parameters

vIndex
Required. Number that specifies the one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCProtocolDefinition. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCProtocolDefinitions


FPCProtocolDefinitions.Refresh Method

Reads all of the protocols from persistent storage, discarding any changes to the current protocols that were not saved.

Syntax

FPCProtocolDefinitions.Refresh()

Applies To

FPCProtocolDefinitions


FPCProtocolDefinitions.Remove Method

Removes the given object from the collection.

Syntax

FPCProtocolDefinitions.Remove( vIndex )

Parameters

vIndex
Required. One-based index of the object to remove.

Applies To

FPCProtocolDefinitions

See Also

FPCProtocolDefinition


FPCProtocolDefinitions.Save Method

Saves all the protocols in the collection to persistent storage.

Syntax

FPCProtocolDefinitions.Save()

Applies To

FPCProtocolDefinitions


FPCProtocolDefinitions.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCProtocolDefinitions collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCProtocolDefinitions.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCProtocolDefinitions


FPCProtocolRule Object

The FPCProtocolRule object represents a single proxy protocol rule. A protocol rule defines a set of protocols that are permitted for certain users at certain times. These times are defined by a schedule.

A protocol rule can apply to one of the following:

  • A specified set of protocols.
  • All IP traffic. This includes all connection combinations, even those that are not designated as a protocol within the protocols collection.

You could use this object to create a rule that allows, for example, the FTP protocol but only during nonbusiness hours. To define a schedule of nonbusiness hours, use the FPCSchedule object.

This object is a member of the FPCProtocolRules collection.

Note to C++ Programmers

This object implements the IFPCProtocolRule interface.

Methods

The following table lists the methods of the FPCProtocolRule object.

Method | Description
Refresh | Reads the cache configuration from persistent storage, discarding any changes to it that were not saved.
Save | Saves the state of the rule to persistent storage.
SetAppliesAlways | Sets the rule to apply always.
SetSchedule | Sets the schedule to which the rule applies.

Properties

The following table lists the properties of the FPCProtocolRule object.

Property | Description
Action | Sets or retrieves whether the rule allows or denies use of protocols. Only relevant for the default rule.
AppliesAlways | Retrieves whether the rule applies at all times.
AppliesToAccounts | Retrieves the collection of accounts to which the rule applies.
AppliesToMethod | Sets or retrieves the method used for deciding rule applicability.
ClientAddressSetsExcluded | Retrieves the collection of client sets to which the rule does not apply.
ClientAddressSetsUsed | Retrieves the collection of client sets to which the rule applies.
Description | Sets or retrieves the description of the set.
Enabled | Sets or retrieves whether the rule is enabled.
Name | Sets or retrieves the name of the proxy protocol rule.
ProtocolSelectionMethod | Sets or retrieves whether the rule applies to all IP traffic or specified protocols.
ScheduleUsed | Retrieves the name of the FPCRef object that is used to define the times when the rule applies..
SpecifiedProtocols | Returns specified plug-in protocols.
VendorParametersSets | Retrieves a reference to an object for storing and loading of custom data into the FPCProtocolRule object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProtocolRule.Action Property

Sets or retrieves whether the rule allows or denies use of protocols. Only relevant for the default rule.

Syntax

FPCProtocolRule.Action [ = bProtocolRuleAction ]

Possible Values

ProtocolRuleAction
Defines whether the rule permits or denies protocols. . It can have a value from the FpcProtocolRuleAction enumerated type.

The property is read-write.

Applies To

FPCProtocolRule


FPCProtocolRule.AppliesAlways Property

Retrieves whether the rule applies at all times.

Syntax

ProtocolRule.AppliesAlways [ = bApplies ]

Possible Values

bApplies
Boolean value that has either of two settings:
Setting | Meaning
TRUE | Rule applies always to content.
FALSE | Rule does not apply to all content.

The property is read-only. It can be set to VARIANT_TRUE by calling the SetAppliesAlways method. It will be set to VARIANT_FALSE if you call the SetSchedule method. When this property is set to VARIANT_FALSE, the schedule defined by the ScheduleUsed property will define the times at which the rule applies.

Applies To

FPCProtocolRule


FPCProtocolRule.AppliesToAccounts Property

Retrieves the collection of accounts to which the rule applies.

Syntax

[ collFPCAccounts = ] FPCProtocolRule.AppliesToAccounts

Possible Values

collFPCAccounts
Reference to the FPCAccounts collection.

The property is read-only.

Applies To

FPCProtocolRule


FPCProtocolRule.AppliesToMethod Property

Sets or retrieves the method used for deciding the rule's applicability to users.

Syntax

FPCProtocolRule.AppliesToMethod [ = AppliesToType ]

Possible Values

AppliesToType
Value from the FpcAppliesToType enumeration that indicates to what type of request the rule will apply:

The property is read-write.

Applies To

FPCProtocolRule


FPCProtocolRule.ClientAddressSetsExcluded Property

Retrieves the collection of client sets to which the rule does not apply.

Syntax

[ collFPCRefs = ] FPCProtocolRule.ClientAddressSetsExcluded

Possible Values

collFPCRefs
Reference to an FPCRefs collection that contains references to the client sets excluded.

The property is read-only.

Applies To

FPCProtocolRule


FPCProtocolRule.ClientAddressSetsUsed Property

Retrieves the collection of client sets to which the rule applies.

Syntax

[ collFPCRefs = ] FPCProtocolRule.ClientAddressSetsUsed

Possible Values

collFPCRefs
Reference to an FPCRefs collection that contains references to the client sets used.

The property is read-only.

Applies To

FPCProtocolRule


FPCProtocolRule.Description Property

Sets or retrieves the description of the rule.

Syntax

FPCProtocolRule.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description.

The property is read-write.

Applies To

FPCProtocolRule


FPCProtocolRule.Enabled Property

Sets or retrieves whether the rule is enabled.

Syntax

FPCProtocolRule.Enabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of two settings:
Setting | Meaning
TRUE | Rule is enabled.
FALSE | Rule is disabled.

The property is read-write.

Applies To

FPCProtocolRule


FPCProtocolRule.Name Property

Sets or retrieves the name of the protocol rule.

Syntax

FPCProtocolRule.Name [ = sName ]

Possible Values

sName
String that specifies the protocol rule's name.

The property is read-write.

Applies To

FPCProtocolRule


FPCProtocolRule.ProtocolSelectionMethod Property

Sets or retrieves whether the rule applies to all IP traffic or specified protocols.

Syntax

FPCProtocolRule.ProtocolSelectionMethod [ = ProtocolSelectionType ]

Possible Values

ProtocolSelectionType
Value from the FpcProtocolSelectiontype enumeration.

The property is read-write.

Applies To

FPCProtocolRule


FPCProtocolRule.Refresh Method

Reads the object configuration from persistent storage, discarding any changes to it that were not saved.

Syntax

FPCProtocolRule.Refresh()

Applies To

FPCProtocolRule


FPCProtocolRule.Save Method

Saves the state of the rule to persistent storage.

Syntax

FPCProtocolRule.Save()

Applies To

FPCProtocolRule


FPCProtocolRule.ScheduleUsed Property

Retrieves the name of the FPCRef object that is used to define the times when the rule applies.

Syntax

[ oFPCRef = ] FPCProtocolRule.ScheduleUsed

Possible Values

oFPCRef
The FPCRef object that is used to define the times when the rule applies.

The property is read only.

Applies To

FPCProtocolRule


FPCProtocolRule.SetAppliesAlways Method

Sets the rule to always apply. Thus, when the SetAppliesAlways method is enabled, the ScheduleUsed property becomes meaningless.

Syntax

FPCProtocolRule.SetAppliesAlways()

Applies To

FPCProtocolRule


FPCProtocolRule.SetSchedule Method

Sets the schedule to which the rule applies. This method sets the AppliesAlways property to FALSE.

Syntax

FPCProtocolRule.SetSchedule( sScheduleName, ItemScope )

Parameters

sScheduleName
String specifying the name of the schedule to which the rule applies.
ItemScope
Item scope. It can have a value from the FpcItemScope enumeration.

Applies To

FPCProtocolRule


FPCProtocolRule.SpecifiedProtocols Property

Returns an FPCRefs collection of FPCRef objects that point to the protocols to which the rule applies.

Syntax

[ collFPCRefs = ]FPCProtocolRule.SpecifiedProtocols

Return values

collFPCRefs
An FPCRefs collection.

Example

The following code illustrates the use of the SpecifiedProtocols property.

  Dim objFPC As New FPCLib.FPC
  Dim MyProtocolRules As FPCProtocolRules
  Dim myarray As FPCArray
  Set myarray = objFPC.Arrays.GetContainingArray
  Dim rule As FPCProtocolRule

  Set MyProtocolRules = myarray.ArrayPolicy.ProtocolRules
  Set rule = MyProtocolRules.Add("Web access")
  rule.Action = fpcActionAllow
  rule.Description = "Basic web access to everyone"
  rule.Enabled = True
  rule.ProtocolSelectionMethod = fpcSpecifiedProtocols
  rule.SpecifiedProtocols.Add ("HTTP")
  rule.SpecifiedProtocols.Add ("HTTP-S")
  rule.SetAppliesAlways
  MyProtocolRules.Save

Applies To

FPCProtocolRule


FPCProtocolRule.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCProtocolRule object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCProtocolRule.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCProtocolRule


FPCProtocolRules Collection

The FPCProtocolRules collection provides access to a group of FPCProtocolRule objects. This collection is a property of the FPCEnterprisePolicy object and the FPCArrayPolicy object.

Note to C++ Programmers

This collection implements the IFPCProtocolRules interface.

Methods

The following table lists the methods of the FPCProtocolRules collection.

Method | Description
Add | Creates a new rule, adds it to the collection, and returns a reference to it.
Item | Retrieves the given FPCProtocolRule object from the collection.
Refresh | Reads all the rule objects from persistent storage, discarding any changes to the current rule objects that were not saved.
Remove | Removes a protocol rule object from the collection.
Save | Saves all modified protocol rules to persistent storage.

Properties

The following table lists the properties of the FPCProtocolRules collection.

Property | Description
Count | Retrieves the number of rule objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading of custom data into the FPCProtocolRule object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProtocolRules.Add Method

Creates a new rule, adds it to the collection, and returns a reference to it.

Syntax

[ oFPCProtocolRule = ] FPCProtocolRules.Add( sRuleName )

Parameters

sRuleName
Required. String that specifies the name of the rule. For intrinsic protocols, specify a string of zero length (not null).

Return Value

oFPCProtocolRule
Reference to the FPCProtocolRule object.

Applies To

FPCProtocolRules


FPCProtocolRules.Count Property

Retrieves the number of rule objects in the collection.

Syntax

[ iCount = ] FPCProtocolRules.Count

Possible Values

iCount
Integer value that specifies the number of rule objects.

The property is read-only.

Applies To

FPCProtocolRules

See Also

FPCProtocolRule


FPCProtocolRules.Item Method

Retrieves the given FPCProtocolRule object from the collection.

Syntax

[ vItem = ] FPCProtocolRules.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCProtocolRule. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCProtocolRules


FPCProtocolRules.Refresh Method

Reads all the rule objects from persistent storage, discarding any changes to the current rule objects that were not saved.

Syntax

FPCProtocolRules.Refresh()

Applies To

FPCProtocolRules


FPCProtocolRules.Remove Method

Removes a protocol rule object from the collection.

Syntax

FPCProtocolRules.Remove( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to remove.

Applies To

FPCProtocolRules

See Also

FPCProtocolRule


FPCProtocolRules.Save Method

Saves all modified protocol rules to persistent storage.

Syntax

FPCProtocolRules.Save()

Applies To

FPCProtocolRules


FPCProtocolRules.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCProtocolRules collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCProtocolRules.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCProtocolRules


FPCProxyClientConfig Object

The FPCProxyClientConfig object represents information about the proxy client configuration in a domain array. This object is a property of the FPCArray object.

Note to C++ Programmers

This object implements the IFPCProxyClientConfig interface.

Methods

The following table lists the methods of the FPCProxyClientConfig object.

Method | Description
Refresh | Reads all the items from persistent storage, discarding any changes to the current configuration that were not saved.
Save | Saves all the configuration information to persistent storage.

Properties

The following table lists the properties of the FPCProxyClientConfig object.

Property | Description
Browser | Retrieves a reference to an object that allows access to the configuration of the Web proxy client browser configuration.
Firewall | Retrieves a reference to an object that allows access to the configuration of the Firewall client.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProxyClientConfig.Browser Property

Retrieves a reference to an object that allows access to the configuration of the Web proxy client browser configuration.

Syntax

[ oBrowserClientConfig = ] FPCProxyClientConfig.Browser

Return Value

oBrowserClientConfig
Variant. Returns an object if successful; NULL otherwise.

Applies To

FPCProxyClientConfig

See Also

FPCWebBrowserClientConfig


FPCProxyClientConfig.Firewall Property

Retrieves a reference to an object that allows access to the configuration of the Firewall client.

Syntax

[ oFirewallClientConfig = ] FPCProxyClientConfig.Firewall

Return Value

oFirewallClientConfig
Variant. Returns an object if successful; NULL otherwise.

Applies To

FPCProxyClientConfig

See Also

FPCFirewallClientConfig


FPCProxyClientConfig.Refresh Method

Reads all the items from persistent storage, discarding any changes to the current configuration that were not saved.

Syntax

FPCProxyClientConfig.Refresh()

Applies To

FPCProxyClientConfig


FPCProxyClientConfig.Save Method

Saves all the configuration information to persistent storage.

Syntax

FPCProxyClientConfig.Save()

Applies To

FPCProxyClientConfig


FPCProxyTunnelPortRange Object

The FPCProxyTunnelPortRange object provides access to the tunnel port range.

A tunnel port allows ISA to work as a data pump for communication to particular ports on an external server. Since this effectively bypasses ISA protocol rules, the external port ranges for which this is possible are set by default to 443 - 443; that is, the single port 443 (SSL), and to 563 - 563, the single port 563 (NNTP). You can use the FPCProxyTunnelPortRange object to change the port range in which a tunnel port can be created.

Note to C++ Programmers

This collection implements the IFPCProxyTunnelPortRange interface.

Methods

The following table lists the methods of the FPCProxyTunnelPortRange object.

Method | Description
Refresh | Reads the object from persistent storage, discarding any changes to the object that were not saved.
Save | Saves the object's configuration information to persistent storage.

Properties

The following table lists the properties of the FPCProxyTunnelPortRange object.

Property | Description
TunnelHighPort | Sets the high end of the port range.
TunnelLowPort | Set the low end of the port range.
Name | Returns the name of the port range.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProxyTunnelPortRange.Name Property

Sets or retrieves the tunnel port range name.

Syntax

[ sName = ] FPCProxyTunnelPortRange.Name

Possible Values

sName
String that specifies the tunel port range name.

The property is read-write.

Applies To

FPCProxyTunnelPortRange


FPCProxyTunnelPortRange.Refresh Method

Reads all the items from persistent storage, discarding any changes that were not saved.

Syntax

FPCProxyTunnelPortRange.Refresh()

Applies To

FPCProxyTunnelPortRange


FPCProxyTunnelPortRange.Save Method

Saves the object to persistent storage.

Syntax

FPCProxyTunnelPortRange.Save()

Applies To

FPCProxyTunnelPortRange


FPCProxyTunnelPortRange.TunnelHighPort Property

Sets or retrieves the high end of the port range.

Syntax

FPCProxyTunnelPortRange.TunnelHighPort [ = lHighPort ]

Possible Values

lHighPort
Long value that specifies the high end of the port range.

The property is read-write.

Applies To

FPCProxyTunnelPortRange


FPCProxyTunnelPortRange.TunnelLowPort Property

Sets or retrieves the low end of the port range.

Syntax

FPCProxyTunnelPortRange.TunnelLowPort [ = lLowPort ]

Possible Values

lLowPort
Long value that specifies the low end of the port range.

The property is read-write.

Applies To

FPCProxyTunnelPortRange


FPCProxyTunnelPortRanges Collection

The FPCProxyTunnelPortRanges collection provides access to a group of FPCProxyTunnelPortRange objects.

Note to C++ Programmers

This collection implements the IFPCProxyTunnelPortRanges interface.

Methods

The following table lists the methods of the FPCProxyTunnelPortRanges collection.

Method | Description
AddRange | Creates a new FPCProxyTunnelPortRange object in the collection and returns a reference to it.
Item | Retrieves the given FPCProxyTunnelPortRange object from the collection.
Refresh | Reads all objects in the collection from persistent storage, discarding any changes to current FPCProxyTunnelPortRanges entries that were not saved.
Remove | Removes an FPCProxyTunnelPortRange object from the collection.
Save | Saves all the objects in the collection to persistent storage.

Properties

The following table lists the properties of the FPCProxyTunnelPortRanges collection.

Property | Description
Count | Retrieves the number of FPCProxyTunnelPortRange objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProxyTunnelPortRanges.AddRange Method

Creates a new FPCProxyTunnelPortRange object in the collection and returns a reference to it.

Syntax

[ oFPCProxyTunnelPortRange = ] FPCProxyTunnelPortRanges.Add( sName, lLowPort, lHighPort )

Parameters

sName
Required. String that specifies the name of the new FPCProxyTunnelPortRange entry.
lLowPort
Required. Long value that specifies the low end of the port range..
lHighPort
Required. Long value that specifies the high end of the port range.

Return Values

oFPCProxyTunnelPortRange
Reference to an FPCProxyTunnelPortRange object.

Applies To

FPCProxyTunnelPortRanges


FPCProxyTunnelPortRanges.Count Property

Retrieves the number of FPCProxyTunnelPortRange objects in the collection.

Syntax

[ lCount = ] FPCProxyTunnelPortRanges.Count

Possible Values

lCount
Long value that specifies the number of FPCProxyTunnelPortRange objects.

The property is read-only.

Applies To

FPCProxyTunnelPortRanges


FPCProxyTunnelPortRanges.Item Method

Retrieves the given FPCProxyTunnelPortRange object from the collection.

Syntax

[ vItem = ] FPCProxyTunnelPortRanges.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCProxyTunnelPortRange. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCProxyTunnelPortRanges


FPCProxyTunnelPortRanges.Refresh Method

Reads all objects from persistent storage, discarding any changes that were not saved.

Syntax

FPCProxyTunnelPortRanges.Refresh()

Applies To

FPCProxyTunnelPortRanges


FPCProxyTunnelPortRanges.Remove Method

Removes an FPCProxyTunnelPortRange object from the collection.

Syntax

FPCProxyTunnelPortRanges.Remove( vItem )

Parameters

vItem
Required. One-based index of the object to remove.

Applies To

FPCProxyTunnelPortRanges


FPCProxyTunnelPortRanges.Save Method

Saves all items in the collection to persistent storage.

Syntax

FPCProxyTunnelPortRanges.Save()

Applies To

FPCProxyTunnelPortRanges


FPCPublishing Object

The FPCPublishing object represents a container for two subobjects that represents the two publishing features of ISA, and their associated rules:

  • Server publishing processes incoming requests to internal servers, such as Simple Mail Transfer Protocol (SMTP) servers, File Transfer Protocol (FTP) servers, Structured Query Language (SQL) servers, and others. Requests are forwarded downstream to an internal server, located behind the ISA Server computer. Server publishing rules determine how server publishing functions, essentially filtering all incoming and outgoing requests through the ISA Server computer. PNAT server mappings are used for server publishing.
  • Web publishing processes incoming requests for Hypertext Transfer Protocol (HTTP) objects on an internal Web server. Web publishing rules determine how ISA Server should intercept incoming requests for HTTP objects and whether ISA Server should respond on behalf of the Web server. Requests are forwarded downstream to an internal Web server, located behind the ISA Server computer.

Note to C++ Programmers

This collection implements the IFPCPublishing interface.

Methods

The following table lists the methods of the FPCPublishing object.

Method | Description
Refresh | Reads all the objects in the collection from persistent storage, discarding any changes that were not saved..
Save | Saves the current object values. This method must be called to save any changes to persistent storage.

Properties

The following table lists the properties of the FPCPublishing object.

Property | Description
PNATServerMappings | Retrieves a collection of FPCPNATServerMapping objects used for other protocols publishing.
VendorParametersSets | Retrieves a reference to an object used to access a vendor's data.
WebPublishingRules | Retrieves a collection of all Web publishing rules.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCPublishing.PNATServerMappings Property

Retrieves the collection of Secure network address translation (SecureNAT) server address mappings.

Syntax

[ collFPCPNATServerMappings = ] FPCPublishing.FPCPNATServerMappings

Possible Values

collFPCPNATServerMappings
Reference to the FPCPNATServerMappings collection, which contains the Secure NAT server address mappings.

The property is read-only.

Applies To

FPCPublishing


FPCPublishing.Refresh Method

Reads all items from persistent storage, discarding any changes that were not saved.

Syntax

FPCPublishing.Refresh()

Applies To

FPCPublishing


FPCPublishing.Save Method

Saves all the items in the collection to persistent storage.

Syntax

FPCPublishing.Save()

Applies To

FPCPublishing


FPCPublishing.VendorParametersSets Property

Retrieves a reference to an object used to access a vendor's data.

Syntax

[ collFPCVendorParametersSets = ] FPCPublishing.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCPublishing


FPCPublishing.WebPublishingRules Property

Retrieves a collection of all Web publishing rules.

Syntax

[ collFPCWebPublishingRules = ] FPCPublishing.WebPublishingRules

Possible Values

collFPCWebPublishingRules
Reference to the FPCWebPublishingRules collection.

Applies To

FPCPublishing


FPCRasPhoneBookEntries Collection

The FPCRasPhoneBookEntries collection provides access to a group of telephone book entry names from the Remote Access Service (RAS) phone book of an ISA Server computer or ISA array. This object is a property of the FPCServer object.

Note This collection is not part of persistent storage and retrieves data from the phone-book file of the specified server.

Note to C++ Programmers

This collection implements the IFPCRasPhoneBookEntries interface.

Methods

The following table lists the methods of the FPCRasPhoneBookEntries collection.

Method | Description
Item | Retrieves the phone book entries in the given index from the collection.
Refresh | Reads all the phone book entries from the RAS phone book.

Properties

The following table lists the properties of the FPCRasPhoneBookEntries collection.

Property | Description
Count | Retrieves the number of phone book entries in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCRasPhoneBookEntries.Count Property

Retrieves the number of phone book entries in the collection.

Syntax

[ iCount = ] FPCRasPhoneBookEntries.Count

Possible Values

iCount
Integer that specifies the number of phone entry names.

The property is read-only.

Applies To

FPCRasPhoneBookEntries


FPCRasPhoneBookEntries.Item Method

Retrieves the phone book entries in the given index from the collection. The return value is a variant that contains the name of the entry. The return value is -1 if the entry specified by the vIndex parameter does not exist.

Syntax

[ item = ] FPCRasPhoneBookEntries.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
Returns a variant that contains the name of the entry, or -1 if the entry specified by vIndex does not exist..

Applies To

FPCRasPhoneBookEntries


FPCRasPhoneBookEntries.Refresh Method

Reads all the phone book entries from the RAS phone book by using an RPC call. The FPCRasPhoneBookEntries collection is not part of persistent storage and retrieves data from the phone-book file of the specified server. An RPC call is used to query ISA services about its sessions because the information is dynamic.

Syntax

FPCRasPhoneBookEntries.Refresh()

Applies To

FPCRasPhoneBookEntries


FPCRef Object

The FPCRef object is used to represent a reference to an object within a rule.

This object is a member of the FPCRefs collection.

Note to C++ Programmers

This object implements the IFPCRef interface.

Methods

The following table lists the methods of the FPCRef object.

Method | Description
Refresh | Reads the data from persistent storage.
Save | Saves the data to persistent storage.

Properties

The following table lists the properties of the FPCRef object.

Property | Description
ApplicationFilterGuid | Retrieves the GUID that identifies the application filter. The vendor of the application filter provides the GUID. For a nonapplication filter protocol this value would be an empty string.
Name | Retrieves the name of object referenced by the object.
Scope | Retrieves a value from the FpcItemScope enumeration that specifies the scope of this object.
VendorParametersSets | Retrieves a reference to an object used to access a vendor's data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCRef.ApplicationFilterGuid Property

Retrieves the globally unique identifier (GUID) that identifies the application filter. The vendor of the application filter provides the GUID. For a nonapplication filter protocol this value would be an empty string.

Syntax

[ sGuid = ] FPCRef.ApplicationFilterGuid

Possible Values

sGuid
String that specifies the GUID that identifies the application filter.

The property is read-only.

Applies To

FPCRef


FPCRef.Name Property

Retrieves the name of the object referenced by the FPCRef object.

Syntax

[ sName = ] FPCRef.Name

Possible Values

sName
String that specifies the name.

The property is read-only.

Applies To

FPCRef


FPCRef.Refresh Method

Reads the data from persistent storage.

Syntax

FPCRef.Refresh()

Applies To

FPCRef


FPCRef.Save Method

Saves the data to persistent storage.

Syntax

FPCRef.Save()

Applies To

FPCRef


FPCRef.Scope Property

Retrieves a value from the FpcItemScope enumeration that specifies the scope of this object.

Syntax

[ ItemScope = ] FPCRef.Scope

Possible Values

ItemScope
Item scope. It can have a value from the FpcItemScope enumeration.

The property is read-only.

Applies To

FPCRef


FPCRef.VendorParametersSets Property

Retrieves a reference to an object that is used to access a vendor's data.

Syntax

[ collFPCVendorParametersSets = ] FPCRef.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCRef


FPCRefs Collection

The FPCRefs collection represents a group of objects that are used by a rule. FPCRefs can contain references to client sets, protocols, or content groups. Note that each instance of FPCRefs will contain a homogenous set of FPCRef objects.

This object is a property of the FPCSiteAndContentRule, FPCWebPublishingRule, FPCBandwidthRule and FPCProtocolRule objects.

Note to C++ Programmers

This collection implements the IFPCRefs interface.

Methods

The following table lists the methods of the FPCRefs collection.

Method | Description
Add | Adds a new FPCRef object to the collection.
Exists | Returns TRUE if an object having the specified properties currently exists in the collection.
Item | Retrieves the given FPCRef object from the collection.
Refresh | Reads all FPCRef objects from persistent storage, discarding any changes to the current object that were not saved.
Remove | Removes an FPCRef object from the collection.
RemoveAll | Removes all entries from the collection.
RemoveSpecified | Removes an object identified by its properties.
Save | Saves the collection data to persistent storage.

Properties

The following table lists the properties of the FPCRefs collection.

Property | Description
Count | Retrieves the number of items collection.
VendorParametersSets | Retrieves a reference to an object used to access a vendor's data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCRefs.Add Method

Adds a new FPCRef object to the collection.

Syntax

[ oFPCRef = ] FPCRefs.Add( sName, sPluginGuid, ItemScope )

Parameters

sName
Required. String that specifies the name of the object to be added.
sPluginGuid
Optional. String that specifies the GUID of the plug in if the object being added represents an application filter protocol.
ItemScope
Item scope. It can have a value from the FpcItemScope enumeration.

Return Values

oFPCRef
Returns a reference to the new FPCRef object.

Applies To

FPCRefs


FPCRefs.Count Property

Retrieves the number of items collection.

Syntax

[ iCount = ] FPCRefs.Count

Possible Values

iCount
Integer value that specifies the number of protocols.

The property is read-only.

Applies To

FPCRefs


FPCRefs.Exists Method

Returns TRUE if an object that has the specified properties exists in the collection.

Syntax

[ bExists = ] FPCRefs.Exists ( sName, PluginGuid, Scope )

Parameters

sName
Required. String that specifies the name of the object.
PluginGuid
Optional. String that specifies the GUID of the plug in if the object represents an application filter protocol.
Scope
Optional. A value from the FpcItemScope enumeration.

Return Values

bExists
A Boolean value that has either of these settings:
Setting | Meaning
TRUE | An object that has the specified properties exists in the collection.
FALSE | An object that has the specified properties does not exist in the collection.

Applies To

FPCRefs


FPCRefs.Item Method

Retrieves the given FPCRef object from the collection.

Syntax

[ vItem = ] FPCRefs.Item( vIndex )

Parameters

vIndex
One-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCRef. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCRefs


FPCRefs.Refresh Method

Reads all the FPCRef objects from persistent storage, discarding any changes to the current object that were not saved.

Syntax

FPCRefs.Refresh()

Applies To

FPCRefs


FPCRefs.Remove Method

Removes an FPCRef object from the collection.

Syntax

FPCRefs.Remove( vIndex )

Parameters

vIndex
Name or one-based index of the object to be removed.

Applies To

FPCRefs


FPCRefs.RemoveAll Method

Removes all FPCRef objects from the collection.

Syntax

FPCRefs.RemoveAll

Applies To

FPCRefs


FPCRefs.RemoveSpecified Method

Removes an object identified by its properties.

Syntax

FPCRefs.RemoveSpecified ( sName, sPluginGuid, ItemScope )

Parameters

sName
Required. String that specifies the name of the object to be removed.
sPluginGuid
String that specifies the GUID of the plug in if the object being removed represents an application filter protocol.
ItemScope
A value from the FpcItemScope enumeration.

Applies To

FPCRefs


FPCRefs.Save Method

Saves the collection data to persistent storage.

Syntax

FPCRefs.Save()

Applies To

FPCRefs


FPCRefs.VendorParametersSets Property

Retrieves a reference to an object used to access a vendor's data.

Syntax

[ collFPCVendorParametersSets = ] FPCRefs.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCRefs


FPCRoutingRule Object

The FPCRoutingRule object represents a single routing rule of an ISA domain array. Routing rules redirect client requests within domain arrays of ISA servers. Routing rules determine whether a Web proxy client request is sent directly to the Internet, to another upstream proxy server, or to an alternate destination. You can use this object to access all attributes of each routing rule of the domain array, such as changing the destination set to which the rule applies or changing the URL to which to redirect, if that is the outcome of applying the rule.

This object is a member of the FPCRoutingRules collection.

Note to C++ Programmers

This object implements the IFPCRoutingRule interface.

Methods

The following table lists the methods of the FPCRoutingRule object.

Method | Description
Refresh | Reads the rule from persistent storage, discarding any changes to the current rule that were not saved.
Save | Saves the rule to persistent storage.
SetDestination | Sets the destinations to which the rule applies.

Properties

The following table lists the properties of the FPCRoutingRule object.

Property | Description
AppliesToDestination | Sets or retrieves the type of destination to which the rule applies.
Description | Sets or retrieves the description of the rule.
DestinationSetUsed | Sets or retrieves the name of the FPCDestinationSet collection used to define the destination to which the rule applies.
Enabled | Sets or retrieves whether this rule is enabled.
IsDefault | Retrieves whether the rule is pre-installed and cannot be deleted.
Name | Sets or retrieves the name of the rule.
NeverCacheResponse | Sets or retrieves whether all responses from the publishing server are never cached.
NonSecureProtocolRedirection | Sets or retrieves the protocol used when delegating a request that came on a nonsecure channel.
Order | Retrieves the rule's order of execution in relation to the other rules.
PrimaryRoute | Retrieves a reference to an object that represents the specific proxy or domain array of the main (primary) route.
SecureProtocolRedirection | Sets or retrieves the protocol used when delegating a request that came on a secure channel.
SSLClientCertificate | Sets or retrieves the client certificate to use when authenticating with the publishing server.
SSLRequireSecureChannel | Sets or retrieves whether or not a secure channel is required.
UseCacheCondition | Sets or retrieve the situation in which a cache should be used instead of the routing action specified.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCRoutingRule object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCRoutingRule.AppliesToDestination Property

Sets or retrieves the type of destination to which the rule applies.

Syntax

[ DestinationSelection = ] FPCRoutingRule.AppliesToDestination

Possible Values

DestinationSelection
Type of destination to which the rule applies. It can have a value of the FpcDestinationSelection enumerated type.

The property is read-only. It can be set by means of the SetDestination method.

Applies To

FPCRoutingRule


FPCRoutingRule.Description Property

Sets or retrieves the description of the rule.

Syntax

FPCRoutingRule.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the rule.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.DestinationSetUsed Property

Retrieves the name of the FPCRef object that is used to define the destination to which the rule applies.

Syntax

[ oFPCRef = ] FPCRoutingRule.DestinationSetUsed

Possible Values

oFPCRef
Reference to a FPCRef object that specifies the name of the destination set to which the rule applies.

The property is read-only. It can be set through the SetDestination method.

Applies To

FPCRoutingRule


FPCRoutingRule.Enabled Property

Sets or retrieves whether this rule is enabled.

Syntax

FPCRoutingRule.Enabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | This rule is enabled.
FALSE | This rule is disabled.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.IsDefault Property

Retrieves whether the rule is pre-installed and cannot be deleted.

Syntax

[ bDefault = ] FPCRoutingRule.IsDefault

Possible Values

bDefault
Boolean value that has either of two settings:
Setting | Meaning
TRUE | Rule is pre-installed.
FALSE | Rule is not pre-installed.

The property is read-only.

Applies To

FPCRoutingRule


FPCRoutingRule.Name Property

Sets or retrieves the name of the rule.

Syntax

FPCRoutingRule.Name [ = sName ]

Possible Values

sName
String that specifies the name of the rule.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.NeverCacheResponse Property

Sets or retrieves whether all responses from the Web publishing server are never cached.

Syntax

FPCRoutingRule.NeverCacheResponse [ = bCache ]

Possible Values

bCache
Boolean value that has either of two settings:
Setting | Meaning
TRUE | Does not cache all responses from the publishing server.
FALSE | Caches all responses from the publishing server.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.NonSecureProtocolRedirection Property

Sets or retrieves the protocol used when the w3proxy service delegates a request that came on a nonsecure channel.

Syntax

FPCRoutingRule.NonSecureProtocolRedirection [ = FpcPublishProtocolRedirectionType ]

Possible Values

FpcPublishProtocolRedirectionType
It can have a value from the FpcPublishProtocolRedirectionType enumeration.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.Order Property

Retrieves the rule's order of execution in relation to the other rules.

Syntax

[ iOrder = ] FPCRoutingRule.Order

Possible Values

iOrder
Integer value that specifies the order of execution.

The property is read-only.

Applies To

FPCRoutingRule


FPCRoutingRule.PrimaryRoute Property

Retrieves a reference to an object that represents the specific proxy or domain array of the main (primary) route.

Syntax

[ oFPCPrimaryRoute = ] FPCRoutingRule.PrimaryRoute

Possible Values

oFPCPrimaryRoute
Reference to the FPCPrimaryRoute object.

The property is read-only.

Applies To

FPCRoutingRule


FPCRoutingRule.Refresh Method

Reads the rule from persistent storage, discarding any changes to the current rule that were not saved.

Syntax

FPCRoutingRule.Refresh()

Applies To

FPCRoutingRule


FPCRoutingRule.Save Method

Saves the rule to persistent storage.

Syntax

RoutingRule.Save()

Applies To

FPCRoutingRule


FPCRoutingRule.SecureProtocolRedirection Property

Sets or retrieves the protocol used when the w3proxy service delegates a request that came on a secure channel.

Syntax

FPCRoutingRule.SecureProtocolRedirection [ = FpcPublishProtocolRedirectionType ]

Possible Values

FpcPublishProtocolRedirectionType
It can have a value from the FpcPublishProtocolRedirectionType enumeration.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.SetDestination Method

Sets the destinations to which the rule applies.

Syntax

FPCRoutingRule.SetDestination( DestType, sDestinationSet, ItemScope )

Parameters

DestType
[in] Required. Defines the type of destinations. Can have a value of the FpcDestinationSelection enumerated type.
sDestinationSet
[in] Optional. String that specifies the name of the destination set.
ItemScope
[in] Optional. Item scope. It can have a value from the FpcItemScope enumeration.

Applies To

FPCRoutingRule


FPCRoutingRule.SSLClientCertificate Property

Sets or retrieves the client certificate to use when the w3proxy service authenticates with the publishing server.

Syntax

FPCRoutingRule.SSLClientCertificate [ = oFPCSSLCertificate ]

Possible Values

oFPCSSLCertificate
Reference to an FPCSSLCertificate object.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.SSLRequireSecureChannel Property

Sets or retrieves whether or not a secure channel is required.

Syntax

FPCRoutingRule.SSLRequireSecureChannel [ = FpcSSLRequireSecureChannelMode ]

Possible Values

FpcSSLRequireSecureChannelMode
Value from the FpcSSLRequireSecureChannelMode enumeration.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.UseCacheCondition Property

Sets or retrieves the situation in which a cache should be used rather than the routing action specified.

Syntax

FPCRoutingRule.UseCacheCondition [ = RouteCacheAction ]

Possible Values

RouteCacheAction
Type of cache using behavior. It can have a value of the FpcRouteCacheAction enumerated type.

The property is read-write.

Remarks

You can configure whether caching takes precedence over routing; that is, you can specify whether an object should be retrieved from the ISA Server cache or whether the request should be routed to the Internet or another proxy server.

Applies To

FPCRoutingRule


FPCRoutingRule.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCRoutingRule object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCRoutingRule.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCRoutingRule


FPCRoutingRules Collection

The FPCRoutingRules collection provides access to a group of FPCRoutingRule objects in an ISA array. Routing rules redirect client requests within arrays of ISA servers. Routing rules determine whether a Web proxy client request is sent directly to the Internet, to another upstream proxy server, or to an alternate destination. Using the MoveUp and MoveDown methods, you can adjust the order in which the routing rules in the group apply.

The FPCRoutingRule object is a property of the FPCArrayPolicy object.

Note to C++ Programmers

This collection implements the IFPCRoutingRules interface.

Methods

The following table lists the methods of the FPCRoutingRules collection.

Method | Description
Add | Creates a new routing rule, adds it to the collection, and returns a reference to it.
Item | Retrieves the given FPCRoutingRule object from the collection.
MoveDown | Moves the given rule down the ladder of execution.
MoveUp | Moves the given rule up the ladder of execution.
Refresh | Reads all the rules from persistent storage, discarding any changes to the current rules that were not saved.
Remove | Removes a routing rules object from the collection.
Save | Saves all the rules in the collection to persistent storage.

Properties

The following table lists the properties of the FPCRouting Rules collection.

Property | Description
Count | Retrieves the number of routing rule objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCRoutingRules collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCRoutingRules.Add Method

Creates a new routing rule, adds it to the collection, and returns a reference to it.

Syntax

[ oFPCRoutingRule = ] FPCRoutingRules.Add( sRuleName )

Parameters

sRuleName
Required. String that specifies the name of the routing rule.

Return Value

oFPCRoutingRule
Reference to the new FPCRoutingRule object.

Applies To

FPCRoutingRules


FPCRoutingRules.Count Property

Retrieves the number of routing rule objects in the collection.

Syntax

[ iCount = ] FPCRoutingRules.Count

Possible Values

iCount

Integer value that specifies the number of FPCRoutingRule objects.

The property is read-only.

Applies To

FPCRoutingRules


FPCRoutingRules.Item Method

Retrieves the given FPCRoutingRule object from the collection.

Syntax

[ vItem = ] FPCRoutingRules.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem

If successful, returns a reference to an object of type FPCRoutingRule. Otherwise:

  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCRoutingRules


FPCRoutingRules.MoveDown Method

Moves the given rule down the ladder of execution.

Syntax

FPCRoutingRules.MoveDown( iIndex )

Parameters

iIndex
Required. Index (current order) of the rule to move down.

Applies To

FPCRoutingRules

See Also

MoveUp


FPCRoutingRules.MoveUp Method

Moves the given rule up the ladder of execution.

Syntax

FPCRoutingRules.MoveUp( iIndex )

Parameters

iIndex
Required. Index (current order) of the rule to move up.

Applies To

FPCRoutingRules

See Also

MoveDown


FPCRoutingRules.Refresh Method

Reads all the rules from persistent storage, discarding any changes to the current rules that were not saved.

Syntax

FPCRoutingRules.Refresh()

Applies To

FPCRoutingRules


FPCRoutingRules.Remove Method

Removes an FPCRoutingRule object from the collection.

Syntax

FPCRoutingRules.Remove( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to remove.

Applies To

FPCRoutingRules


FPCRoutingRules.Save Method

Saves all the rules in the collection to persistent storage.

Syntax

FPCRoutingRules.Save()

Applies To

FPCRoutingRules


FPCRoutingRules.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCRoutingRules collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCRoutingRules.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCRoutingRules


FPCSchedule Object

The FPCSchedule object defines a schedule. A schedule is defined by groups of hours defined for each day of the week. Each day of the week can have different hour blocks defined. Schedules are applied by ISA to define a set of hours during which a certain configuration detail, such as a site and content rule, applies.

The hour blocks defined by a schedule include the specified time and the one-hour block beyond that time. For example, the hour designated by 2_PM is the one-hour time block of between 2 P.M. and 3 P.M.

The FPCSchedule object is a member of the FPCSchedules collection.

Note to C++ Programmers

This object implements the IFPCSchedule interface.

Methods

The following table lists the methods of the FPCSchedule object.

Method | Description
IsSet | Returns a Boolean variable indicating whether every hour in the given set is part of the schedule template.
Refresh | Reads the template's information from persistent storage, discarding any changes to the template that were not saved.
Save | Saves the template's configuration to persistent storage.
Set | Adds a set of hours to the schedule template.
UnSet | Removes a set of hours from the schedule template.

Properties

The following table lists the properties of the FPCSchedule object.

Property | Description
Description | Sets or retrieves the description of the schedule template.
Name | Sets or retrieves the name of the schedule template.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCSchedule object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSchedule.Description Property

Sets or retrieves the description of the schedule template.

Syntax

FPCSchedule.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the schedule template.

The property is read-write.

Applies To

FPCSchedule


FPCSchedule.IsSet Method

Returns a Boolean variable indicating whether every hour in the given set is part of the schedule template.

Syntax

[ bIsSet = ] FPCSchedule.UnSet( Day, Hour )

Parameters

Day
Value that specifies a day. It can be ALL_WEEK, SUN, MON, and so on.
Hour
Value that specifies an hour or hours. It can be ALL_DAY, AM_0, AM_1, PM_1, PM_2, and so on.

Return Values

bIsSet
Boolean value that receives TRUE if every hour in the set specified by the Day and Hour parameters is part of the schedule template; FALSE otherwise.

Remarks

The hour blocks defined by a schedule include the specified time and the one-hour block beyond that time. For example, the hour designated by 2_PM is the one-hour time block of between 2_PM and 3_PM.

Applies To

FPCSchedule

See Also

Set, UnSet


FPCSchedule.Name Property

Sets or retrieves the name of the schedule template.

Syntax

FPCSchedule.Name [ = sName ]

Possible Values

sName
String that specifies the schedule template name.

The property is read-write.

Applies To

FPCSchedule


FPCSchedule.Refresh Method

Reads the template's information from persistent storage, discarding any changes to the template that were not saved.

Syntax

FPCSchedule.Refresh()

Applies To

FPCSchedule


FPCSchedule.Save Method

Saves the template's configuration to persistent storage.

Syntax

FPCSchedule.Save()

Applies To

FPCSchedule


FPCSchedule.Set Method

Adds a set of hours to the schedule template.

Syntax

FPCSchedule.Set( Day, Hour )

Parameters

Day
Value that specifies a day. It can be ALL_WEEK, SUN, MON, and so on.
Hour
Value that specifies an hour or hours. It can be ALL_DAY, AM_0, AM_1, ..., PM_1, PM_2, ..., and so on.

Example

The following example adds "3AM on Sunday" to the set:

Set(SUM, AM_3)

The following example adds "6AM on every day" to the set:

Set(ALL_WEEK, AM_6)

The following example adds all of Monday to the set:

Set(MON, ALL_DAY)

The following example adds all hours of the week to the set:

Set(ALL_WEEK, ALL_DAY)

Remarks

The hour blocks defined by a schedule include the specified time and the one-hour block beyond that time. For example, the hour designated by 2_P.M. is the one-hour time block of between 2_P.M. and 3_P.M.

Applies To

FPCSchedule

See Also

IsSet, UnSet


FPCSchedule.UnSet Method

Removes a set of hours from the schedule template.

Syntax

FPCSchedule.UnSet( Day, Hour )

Parameters

Day
Value that specifies a day from the schedule template. It can be ALL_WEEK, SUN, MON, and so on.
Hour
Value that specifies an hour or hours. It can be ALL_DAY, AM_0, AM_1, PM_1, PM_2, and so on.

Remarks

The hour blocks defined by a schedule include the specified time and the one-hour block beyond that time. For example the hour designated by 2_PM is the one-hour time block of between 2_PM and 3_PM.

Applies To

FPCSchedule

See Also

IsSet, Set


FPCSchedule.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCSchedule object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCSchedule.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCSchedule


FPCSchedules Collection

The FPCSchedules collection is a collection of FPCSchedule objects. Each object within this schedule defines a schedule. A schedule is defined by groups of hours defined for each day of the week. Each day of the week can have different hour blocks defined. Schedules are used by ISA to define a set of hours during which a certain configuration, such as a site and content rule, applies.

This collection is a property of the FPCPolicyElements object.

Note to C++ Programmers

This collection implements the IFPCSchedules interface.

Methods

The following table lists the methods of the FPCSchedules collection.

Method | Description
Add | Creates a new template in the collection and returns a reference to it.
Item | Retrieves the given FPCSchedule object from the collection.
Refresh | Reads all the FPCSchedule objects from persistent storage, discarding any changes to the objects that were not saved.
Remove | Removes a schedule template from the collection.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCSchedules collection.

Property | Description
Count | Retrieves the number of schedule template objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCSchedules collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSchedules.Add Method

Creates a new template in the collection and returns a reference to it.

Syntax

[ oFPCSchedule = ] FPCSchedules.Add( sName )

Parameters

sName
String that specifies the name of the new template.

Possible Values

oFPCSchedule
Reference to the FPCSchedule object.

Remarks

Newly created schedule templates do not contain any defined hour blocks. You can define hour blocks with the methods of the individual FPCSchedule object.

The additional FPCSchedule object added by this method will not be saved to persistent storage until after the Save method is called.

Applies To

FPCSchedules


FPCSchedules.Count Property

Returns the number of schedule template objects in the collection.

Syntax

[ iCount = ] FPCSchedules.Count

Possible Values

iCount
Integer value that specifies the number of FPCSchedule objects.

The property is read-only.

Applies To

FPCSchedules


FPCSchedules.Item Method

Returns the given FPCSchedule object from the collection.

Syntax

[ vItem = ] FPCSchedules.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCSchedule. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCSchedules


FPCSchedules.Refresh Method

Reads all the FPCSchedule objects from persistent storage, discarding any changes to the objects that were not saved.

Syntax

FPCSchedules.Refresh()

Applies To

FPCSchedules


FPCSchedules.Remove Method

Removes a schedule template from the collection.

Syntax

FPCSchedules.Remove( iIndex )

Parameters

iIndex
Required. Name or one-based index of the FPCSchedule object to remove.

Applies To

FPCSchedules


FPCSchedules.Save Method

Saves the object's configuration to persistent storage.

Syntax

FPCSchedules.Save()

Applies To

FPCSchedules


FPCSchedules.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCSchedules collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCSchedules.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCSchedules


FPCScheduledContentDownload Collection

The FPCScheduledContentDownload collection provides access to all FPCScheduledContentDownloadConfig objects of an ISA Server computer. This collection allows you to create a list of predefined fetching tasks.

The FPCScheduledContentDownload collection is a property of the FPCCacheConfiguration object.

Note to C++ Programmers

This collection implements the IFPCScheduledContentDownload interface.

Methods

The following table lists the methods of the FPCScheduledContentDownload collection.

Method | Description
Add | Creates a new FPCScheduledContentDownloadConfig object in the list and returns a reference to it.
Item | Retrieves the given FPCScheduledContentDownloadConfig object from the collection.
Refresh | Reads all items from persistent storage, discarding any changes to the current FPCScheduledContentDownload collection entries that were not saved.
Remove | Removes an FPCScheduledContentDownloadConfig object from the collection.
Save | Saves all items in the collection to persistent storage.

Properties

The following table lists the properties of the FPCScheduledContentDownload collection.

Property | Description
Count | Retrieves the number of FPCScheduledContentDownloadConfig objects in the collection.
UseProxy | Sets or retrieves the proxy server the scheduled content download uses.
UseProxyPort | Sets or retrieves the port the scheduled content download uses when calling UseProxy.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCScheduledContentDownload.Add Method

Creates a new FPCScheduledContentDownloadConfig object in the list and returns a reference to it.

Syntax

[ oFPCScheduledContentDownloadConfig = ] FPCScheduledContentDownload.Add( sName, sURL )

Parameters

sName
Required. String that specifies the name of a new FPCScheduledContentDownloadConfig object.
sURL
Required. String that specifies the URL.

Return Value

oFPCScheduledContentDownloadConfig
Returns a reference to the new FPCScheduledContentDownloadConfig object.

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownload.Count Property

Retrieves the number of FPCScheduledContentDownloadConfig objects in the collection.

Syntax

[ iCount = ] FPCScheduledContentDownload.Count

Possible Values

iCount
Integer value that specifies the number of FPCScheduledContentDownloadConfig objects.

The property is read-only.

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownload.Item Method

Retrieves the FPCScheduledContentDownloadConfig object from the collection, specified by the method's index parameter.

Syntax

[ vItem = ] FPCScheduledContentDownload.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCScheduledContentDownloadConfig. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownload.Refresh Method

Reads all the items from persistent storage, discarding any changes to the FPCScheduledContentDownload objects that were not saved.

Syntax

FPCScheduledContentDownload.Refresh()

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownload.Remove Method

Removes an FPCScheduledContentDownloadConfig object from the collection.

Syntax

FPCScheduledContentDownload.Remove( vItem )

Parameters

vItem
Required. One-based index or name of the object to remove.

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownload.Save Method

Saves all the items in the collection to persistent storage. It is important to remember that no changes will be saved unless the Save method is called.

Syntax

FPCScheduledContentDownload.Save()

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownload.UseProxy Property

Sets or retrieves the proxy server the scheduled content download uses.

Syntax

FPCScheduledContentDownload.UseProxy [ = sProxy ]

Possible Values

sProxy
String that specifies the proxy to use.

The property is read-write.

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownload.UseProxyPort Property

Sets or retrieves the port the scheduled content download uses when calling UseProxy.

Syntax

FPCScheduledContentDownload.UseProxyPort [ = lUseProxyPort ]

Possible Values

lUseProxyPort
Long value that specifies the port to use.

The property is read-write.

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownload.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCScheduledContentDownload object's storage. The VendorParameterSets property is designed to allow third-party extensions to be integrated into ISA.

Syntax

[ collFPCVendorParametersSets = ] FPCScheduledContentDownload.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownloadConfig Object

The FPCScheduledContentDownloadConfig object defines each pre-fetch task contained in the FPCScheduledContentDownload collection. This collection allows you to create a list of predefined fetching tasks.

The prefetching feature of the ISA Server cache lets you download HTTP content directly to the ISA Server cache, upon request or as scheduled. Prefetching allows you to update the ISA Server cache with HTTP content that you anticipate will be requested by clients in your organization.

You can configure the content that ISA Server should precache. You can also schedule when the content should be cached, available for access directly from the ISA Server cache, rather than from the Internet.

You can use cache prefetching to schedule downloads of HTTP files from a Web site to a local cache. You can download a single URL, multiple URLs, or an entire Web site according to a schedule you specify.

The FPCScheduledContentDownloadConfig object is a member of the FPCScheduledContentDownload collection.

Note to C++ Programmers

This object implements the IFPCScheduledContentDownloadConfig interface.

Methods

The following table lists the methods of the FPCScheduledContentDownloadConfig object.

Method | Description
Refresh | Reads the object's data from persistent storage, discarding any changes to the data that were not saved.
Save | Saves all the object's data to persistent storage.
SetTaskPeriod | Sets the values retrieved through the TaskPeriod and DaysOfWeek properties of the FPCScheduledContentDownloadConfig object.

Properties

The following table lists the properties of the FPCScheduledContentDownloadConfig object.

Property | Description
CacheTextOnly | Sets or retrieves whether to fetch text only.
DaysOfWeek | Sets or retrieves the days of weeks in which to perform fetch (each day is represented by a bit: Sunday—bit 0, Monday—bit 1, and so forth).
Description | Sets or retrieves the description of the FPCScheduledContentDownloadConfig object.
Enabled | Sets or retrieves whether the configuration is enabled.
FetchUrlFlagForce | Sets or retrieves the FETCH_FORCE_CACHE flag, which is passed to the FetchUrl method.
FetchUrlFlagNoArrayRoute | Sets or retrieves the FETCH_NO_ARRAY_ROUTING flag, which is passed to FetchUrl.
FetchUrlFlagSync | Sets or retrieves the FETCH_SYNCHRONOUS flag, which is passed to FetchUrl.
FetchUrlFlagTtlIfNone | Sets or retrieves the FETCH_TTL_IF_NONE flag, which is passed to FetchUrl.
FetchUrlFlagTtlOverride | Sets or retrieves the FETCH_TTL_OVERRIDE flag, which is passed to FetchUrl.
MaxDepth | Sets or retrieves the upper limit of depth to fetch.
MaxPages | Sets or retrieves the upper limit of size to fetch.
Name | Sets or retrieves the name of the FPCScheduledContentDownloadConfig object.
SchedTimeHour | Sets or retrieves the time (hour) to start fetching.
SchedTimeMinute | Sets or retrieves the time (minutes) to start fetching.
StartDateDay | Sets or retrieves the date (day) to start fetching.
StartDateMonth | Sets or retrieves the date (month) to start fetching.
StartDateYear | Sets or retrieves the date (year) to start fetching.
StayInDomain | Sets or retrieves whether to fetch from the initial domain only or from other domains as well.
TaskPeriod | Sets or retrieves the period of time between two prefetches.
TTL | Sets or retrieves the Time-To-Live (TTL) setting of the pages to be fetched.
URL | Sets or retrieves the URL to be fetched.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCScheduledContentDownloadConfig object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCScheduledContentDownloadConfig.CacheTextOnly Property

Sets or retrieves whether to fetch HTML text only or to fetch all HTML objects, including images or sounds.

Syntax

FPCScheduledContentDownloadConfig.CacheTextOnly [ = bCacheTextOnly ]

Possible Values

bCacheTextOnly
Boolean value that has either of two settings:
Setting | Meaning
TRUE | Text only.
FALSE | Cache all HTML objects.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.DaysOfWeek Property

Retrieves the days of weeks in which to perform the fetching task. Each day is represented by a bit. Sunday is bit 0, Monday is bit 1, and so forth. The value of this property is set through the SetTaskPeriod method.

Syntax

[ FpcScheduleDays = ] FPCScheduledContentDownloadConfig.DaysOfWeek

Possible Values

FpcDaysOfWeek
Value from the FpcScheduleDays enumeration.

The property is read-only.

Example

The following code sets the DaysOfWeek property to equal Sunday, Tuesday, and Thursday.

FPCScheduledContentDownloadConfig.DaysOfWeek = 0x15

0x15 is 15 in hexadecimal (which is 21 in decimal). In binary it: 10101. The right bit represents Sunday. It is set to one, so Sunday is set. The second bit represents Monday. Its value is zero, so Monday is not set.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.Description Property

Sets or retrieves the description of the FPCScheduledContentDownloadConfig object.

Syntax

FPCScheduledContentDownloadConfig.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.Enabled Property

Sets or retrieves whether the configuration is enabled.

Syntax

FPCScheduledContentDownloadConfig.Enabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of two settings:
Setting | Meaning
TRUE | Configuration is enabled.
FALSE | Configuration is disabled.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.FetchUrlFlagForce Property

Sets or retrieves the FETCH_FORCE_CACHE flag, which is passed to the FetchUrl method.

Syntax

FPCScheduledContentDownloadConfig.FetchUrlFlagForce [ = bFetchUrlFlagForce ]

Possible Values

bFetchUrlFlagForce
Boolean value that specifies the flag.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.FetchUrlFlagNoArrayRoute Property

Sets or retrieves the FETCH_NO_ARRAY_ROUTING flag, which is passed to the FetchUrl method.

Syntax

FPCScheduledContentDownloadConfig.FetchUrlFlagNoArrayRoute [ = bFetchUrlFlagNoArrayRoute ]

Possible Values

bFetchUrlFlagNoArrayRoute
Boolean value that specifies the flag.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.FetchUrlFlagSync Property

Sets or retrieves the FETCH_SYNCHRONOUS flag, which is passed to the FetchUrl method.

Syntax

FPCScheduledContentDownloadConfig.FetchUrlFlagSync [ = bFetchUrlFlagSync ]

Possible Values

bFetchUrlFlagSync
Boolean value that specifies the flag.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.FetchUrlFlagTtlIfNone Property

Sets or retrieves the FETCH_TTL_IF_NONE flag, which is passed to the FetchUrl method.

Syntax

FPCScheduledContentDownloadConfig.FetchUrlFlagTtlIfNone [ = bFetchUrlFlagTtlIfNone ]

Possible Values

bFetchUrlFlagTtlIfNone
Boolean value that specifies the flag.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.FetchUrlFlagTtlOverride Property

Sets or retrieves the FETCH_TTL_OVERRIDE flag, which is passed to the FetchUrl method.

Syntax

FPCScheduledContentDownloadConfig.FetchUrlFlagTtlOverride [ = bFetchUrlFlagTtlOverride ]

Possible Values

bFetchUrlFlagTtlOverride
Boolean value that specifies the flag.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.MaxDepth Property

Sets or retrieves the upper limit of depth to fetch.

Syntax

FPCScheduledContentDownloadConfig.MaxDepth [ = iMaxDepth ]

Possible Values

iMaxDepth
Integer that specifies the upper limit of term-link depth.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.MaxPages Property

Sets or retrieves the integer that specifies the upper limit in terms of total cache-object size in kilobytes.

Syntax

FPCScheduledContentDownloadConfig.MaxPages [ = iMaxPages ]

Possible Values

iMaxPages
Integer that specifies the upper limit in terms of total cache-object size in kilobytes.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.Name Property

Sets or retrieves the name of the FPCScheduledContentDownloadConfig object.

Syntax

FPCScheduledContentDownloadConfig.Name [ = sName ]

Possible Values

sName
String that specifies the name of the FPCScheduledContentDownloadConfig object.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.Refresh Method

Reads the object's data from persistent storage, discarding any changes to the data that were not saved.

Syntax

FPCScheduledContentDownloadConfig.Refresh()

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.Save Method

Saves all the object's data to persistent storage.

Syntax

FPCScheduledContentDownloadConfig.Save()

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.SchedTimeHour Property

Sets or retrieves the time, in full hours, to start fetching.

Syntax

FPCScheduledContentDownloadConfig.SchedTimeHour [ = iSchedTimeHour ]

Possible Values

iSchedTimeHour
Integer that specifies the hour to start fetching.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.SchedTimeMinute Property

Sets or retrieves the time in minutes to start fetching.

Syntax

FPCScheduledContentDownloadConfig.SchedTimeMinute [ = iSchedTimeMinute ]

Possible Values

iSchedTimeMinute
Integer that specifies the minute to start fetching.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.SetTaskPeriod Method

Sets the values retrieved through the TaskPeriod and DaysOfWeek properties of the FPCScheduledContentDownloadConfig object.

Syntax

FPCScheduledContentDownloadConfig.SetTaskPeriod ( TaskPeriod, DaysOfWeek )

Parameters

TaskPeriod
Task period. It can have a value from the FpcScheduledContentDownloadPeriod enumeration.
DaysOfWeek
Optional. A value from the FpcScheduleDays enumeration. This parameter will be used if TaskPeriod is set to the DownloadSpecifiedDaysOfWeek value of the FpcScheduledContentDownloadPeriod enumeration.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.StartDateDay Property

Sets or retrieves the date, as a day, to start fetching.

Syntax

FPCScheduledContentDownloadConfig.StartDateDay [ = iStartDateDay ]

Possible Values

iStartDateDay
Integer that specifies the day.

The property is read-write.

Remarks

The date to start prefetching is in the form of dd.mm.yyyy, where dd equals the day, mm equals the month, and yyyy equals the year. The day is set by the StartDateDay property, the month is set by the StartDateMonth property, and the year is set by the StartDateYear property.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.StartDateMonth Property

Sets or retrieves the month to start fetching.

Syntax

FPCScheduledContentDownloadConfig.StartDateMonth [ = iStartDateMonth ]

Possible Values

iStartDateMonth
Integer that specifies the month.

The property is read-write.

Remarks

The date to start prefetching is in the form of dd.mm.yyyy, where dd equals the day, mm equals the month, and yyyy equals the year. The day is set by the StartDateDay property, the month is set by the StartDateMonth property, and the year is set by the StartDateYear property.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.StartDateYear Property

Sets or retrieves the year to start fetching.

Syntax

FPCScheduledContentDownloadConfig.StartDateYear [ = iStartDateYear ]

Possible Values

iStartDateYear
Integer that specifies the year.

The property is read-write.

Remarks

The date to start prefetching is in the form of dd.mm.yyyy, where dd equals the day, mm equals the month, and yyyy equals the year. The day is set by the StartDateDay property, the month is set by the StartDateMonth property, and the year is set by the StartDateYear property.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.StayInDomain Property

Sets or retrieves whether to fetch from the initial domain only, or from other domains as well.

Syntax

FPCScheduledContentDownloadConfig.StayInDomain [ = bStayInDomain ]

Possible Values

bStayInDomain
Boolean value that has either of these settings:
Setting | Meaning
TRUE | The traversal will remain in the domain of the root URL.
FALSE | Fetching from initial domain and other domains.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.TaskPeriod Property

Retrieves the period of time between two prefetch actions by an ISA server. TaskPeriod is set through the SetTaskPeriod method.

Syntax

[ ScheduledContentDownloadPeriod = ] FPCScheduledContentDownloadConfig.TaskPeriod

Possible Values

ScheduledContentDownloadPeriod
A value from the FpcScheduledContentDownloadPeriod enumeration.
The property is read-only.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.TTL Property

Sets or retrieves the Time-To-Live (TTL) setting of the pages to be fetched.

Syntax

FPCScheduledContentDownloadConfig.TTL [ = iTTL ]

Possible Values

iTTL
Integer that specifies the TTL.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.URL Property

Sets or retrieves the URL to be fetched.

Syntax

FPCScheduledContentDownloadConfig.URL [ = sURL ]

Possible Values

sURL
String that specifies the URL to be fetched.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCScheduledContentDownloadConfig object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCScheduledContentDownloadConfig.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCScheduledContentDownloadConfig


FPCSecurityDescriptor Object

The FPCSecurityDescriptor object allows you to access security settings of ISA objects. You can also use it to make copies of a security descriptor. This object is a property of every object that supports security settings. Specifically, the FPCSecurityDescriptor object is a property of the FPCArray, FPCEnterprise, and the FPCEnterprisePolicy objects..

Note to C++ Programmers

This object implements the IFPCSecurityDescriptor interface.

Methods

The following table lists the methods of the FPCSecurityDescriptor object.

Method | Description
CopySecurityDescriptor | Returns a copy of the current FPCSecurityDescriptor object.

Properties

The following table lists the properties of the FPCSecurityDescriptor object.

Property | Description
Control | Sets or returns flags that qualify the meaning of the security descriptor.
DaclDefaulted | Sets or returns a flag to indicate whether the DACL is derived from a default mechanism rather than provided explicitly by the original provider of the security descriptor.
DiscretionaryAcl | Sets or returns the values of a discretionary access control list (DACL) that specifies types of access allowed to the object for specified users and groups.
Group | Sets or returns a string that specifies the group to which the owner's security identifier (ID) belongs.
GroupDefaulted | Sets or returns a flag that indicates whether the group information is derived from a default mechanism rather than provided explicitly by the original provider of the security descriptor.
Owner | Sets or returns the owner of the object.
OwnerDefaulted | Sets or returns a flag that indicates whether the owner information is derived from a default mechanism rather than from the original provider of the security descriptor explicitly.
Revision | Sets or returns the revision level of the security descriptor.
SaclDefaulted | Sets or returns a flag that indicates whether the system access control list (SACL) is derived from a default mechanism rather than by the original provider of the security descriptor explicitly.
SystemAcl | Sets or returns an SACL used to generate audit records for the object.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSecurityDescriptor.Control Property

Sets or returns flags that qualify the meaning of the security descriptor. Values are taken from the Win32 SECURITY_DESCRIPTOR_CONTROL structure. See MSDN for more information.

Syntax

FPCSecurityDescriptor.Control [ = lControl ]

Possible Values

lControl
Long. Reference to SECURITY_DESCRIPTOR_CONTROL structure.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.CopySecurityDescriptor Method

Returns a copy of the current FPCSecurityDescriptor object.

Syntax

[ oFPCSecurityDescriptor = ] FPCSecurityDescriptor.CopySecurityDescriptor()

Return Value

oFPCSecurityDescriptor
Reference to an FPCSecurityDescriptor object.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.DaclDefaulted Property

Sets or returns a flag to indicate whether the discretionary access control list (DACL) is derived from a default mechanism rather than provided by the original provider of the security descriptor. For example, if an object's creator does not specify a DACL, the object receives the default DACL from the creator's access token. This flag can affect how the system treats the DACL, with respect to access control entry (ACE) inheritance. The system ignores this flag if the SE_DACL_PRESENT flag is not set.

Syntax

FPCSecurityDescriptor.DaclDefaulted [ = bDaclDefaulted ]

Possible Values

bDaclDefaulted
A Boolean value that indicates whether the DACL is derived from a default mechanism.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.DiscretionaryAcl Property

Sets or returns the values of a discretionary access control list (DACL) that specifies types of access allowed to the object for specified users and groups.

Syntax

FPCSecurityDescriptor.DiscretionaryAcl [ = collFPCAccessControlList ]

Possible Values

collFPCAccessControlList

Reference to an FPCAccessControlList collection that specifies types of access allowed to the object for specified users and groups.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.Group Property

Sets or returns a string that specifies the group to which the owner's security identifier (ID) belongs.

Syntax

FPCSecurityDescriptor.Group [ = sGroup ]

Possible Values

sGroup
String value that specifies the group to which the owner's security ID belongs.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.GroupDefaulted Property

Sets or returns a flag that indicates whether the group information is derived from a default mechanism rather than from the original provider of the security descriptor explicitly.

Syntax

FPCSecurityDescriptor.GroupDefaulted [ = bGroupDefaulted ]

Possible Values

bGroupDefaulted
A Boolean value that indicates whether the group information is derived from a default mechanism rather than fromy the original provider of the security descriptor explicitly.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.Owner Property

Sets or returns the owner of the object.

Syntax

FPCSecurityDescriptor.Owner [ = sOwner ]

Possible Values

sOwner
String value that specifies the owner of the object.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.OwnerDefaulted Property

Sets or returns a flag that indicates whether the owner information is derived from a default mechanism rather than from the original provider of the security descriptor explicitly.

Syntax

FPCSecurityDescriptor.OwnerDefaulted [ = bOwnerDefaulted ]

Possible Values

bOwnerDefaulted
A Boolean value that indicates whether the owner information is derived from a default mechanism rather than from the original provider of the security descriptor explicitly.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.Revision Property

Sets or returns the revision level of the security descriptor.

Syntax

FPCSecurityDescriptor.Revision [ = lRevision ]

Possible Values

lnRevision
Long. Reference to the revision level of the security descriptor.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.SaclDefaulted Property

Sets or returns a flag that indicates whether the system access control list (SACL) is derived from a default mechanism rather than from the original provider of the security descriptor explicitly. This flag can affect how the system treats the SACL, with respect to ACE inheritance. The system ignores this flag if the SE_SACL_PRESENT flag is not set.

Syntax

FPCSecurityDescriptor.SaclDefaulted [ = bSaclDefaulted ]

Possible Values

bSaclDefaulted
Boolean value that indicates whether the SACL is derived from a default mechanism.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.SystemAcl Property

Sets or returns a system access control list (SACL) used to generate audit records for the object.

Syntax

FPCSecurityDescriptor.SystemAcl [ = collFPCAccessControlList ]

Possible Values

collFPCAccessControlList
Reference to an FPCAccessControlList collection used to generate audit records for the object.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCServer Object

The FPCServer object holds a single ISA Server computer within a server domain array. Each object has multiple properties that are used to set configuration settings. Using this object, you can programmatically access drives, available network interface cards (NICs), product information, and other generic server attributes such as a server's name and description.

You use this object to access server-specific configuration from a server within the domain array. Array-specific information is accessed through the FPCServers collection.

This object is a member of the FPCServers collection.

Note to C++ Programmers

This object implements the IFPCServer interface.

Methods

The following table lists the methods of the FPCServer object.

Method | Description
AddIp | Adds an IP on the ISA server.
Refresh | Reads the server's information from persistent storage, discarding any changes to the server that were not saved.
RestartServices | Restarts all previously stopped services.
Save | Saves the server's configuration to persistent storage.
StartFirewallService | Starts Firewall service.
StartScheduledContentDownloadService | Starts the scheduled content download service.
StartWebProxyService | Starts Web proxy service.
StopAllServices | Stops all the running services on current server.
StopFirewallService | Stops the Firewall service.
StopScheduledContentDownloadService | Stops the scheduled content download service.
StopWebProxyService | Stops the Web proxy service.

Properties

The following table lists the properties of the FPCServer object.

Property | Description
AdapterList | Returns a collection of objects representing the available network adapter cards (NICs).
CacheDrives | Returns a collection of cache drive objects in this server.
CreatedTime | Returns a DATE data type that specifies the creation time of the object.
Description | Sets or retrieves the description of the server.
DiskDrives | Returns a collection of disk drive objects in this server.
FirewallServiceStatus | Indicates whether the Firewall service is running on the server.
FirewallServiceUpTime | Returns a DATE value indicating the date since the Firewall service has been working properly.
FirewallSessions | Returns a collection of firewall session objects on this server.
ForwardProxyListenEntries | Returns a collection of FPCListenEntry objects.
FQDN | Returns the Fully Qualified Domain Name (FQDN) of the server.
HttpViaHeaderAlias | Sets or retrieves the ViaHeaderAlias setting of the server, which the Web proxy adds to each HTTP response from this server.
IntraArrayAddress | Returns a reference to the returned key string.
LastModifiedTime | Returns a DATE data type that specifies the last modification time of the object.
LoadFactor | Sets or retrieves the load factor for the server.
Name | Returns the name of the server.
ProductID | Returns the identifier (ID) of the product installed on this server.
ProductVersion | Returns the version of the server.
RasPhoneBookEntries | Returns a collection of Remote Access Service (RAS) phone book entry names in this server.
ReverseProxyListenEntries | Returns a collection of FPCListenEntry objects.
ScheduledContentDownloadServiceStatus | Returns a Boolean value indicating the status of the scheduled content download service.
ScheduledContentDownloadServiceUpTime | Returns a DATE value indicating the from what date forward the scheduled content download service has been working properly.
ServerStatus | Indicates whether the server is connectable.
SignaledAlerts | Returns a reference to the FPCSignaledAlerts collection.
SSLClientCertificates | Returns an FPCSSLCertificates collection that represents SSL client certificates available on the server.
SSLServerCertificates | Returns an FPCSSLCertificates collection representing SSL server certificates available on the server.
VendorParametersSets | Returns a reference to an object for storing and loading custom data into the FPCServer object's storage.
WebProxyServiceStatus | Returns a Boolean value indicating whether the Web proxy is running.
WebProxyServiceUpTime | Returns a DATE value indicating the date since the Web proxy service has been working properly.
WebSessions | Returns a collection of Web session objects in this server.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCServer.AdapterList Property

Returns a collection of objects representing the available network adapter cards (NICs).

Syntax

[ collFPCAdapterList = ] FPCServer.AdapterList

Possible Values

collFPCAdapterList
Reference to the FPCAdapterList collection.

The property is read-only.


FPCServer.AddIP Method

Adds an Internet Protocol (IP) on the ISA server.

Syntax

[ dwResult  = ]FPCServer.AddIP( sIpAddress, dwHelperIp )

Parameters

sIpAddress
String. The IP address to be added.
dwHelperIp
Variable of type DWORD. Another IP address on the server.

Return Value

dwResult
Variable of type DWORD. Will contain NO_ERROR if the IP was successfully added and a WIN32API error code otherwise.

Applies To

FPCServer


FPCServer.CacheDrives Property

Returns a collection of cache drive objects in this server.

Syntax

[ collFPCCacheDrives = ] FPCServer.CacheDrives

Possible Values

collFPCCacheDrives
Reference to the FPCCacheDrives collection.

The property is read-only.

Applies To

FPCServer


FPCServer.CreatedTime Property

Returns a DATE data type that specifies the creation time of the object.

Syntax

[ dCreatedTime = ] FPCServer.CreatedTime

Possible Values

dCreatedTime
Reference to a DATE data type.

The property is read-only.

Applies To

FPCServer


FPCServer.Description Property

Sets or retrieves the description of the server.

Syntax

FPCServer.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the server.

The property is read-write.

Applies To

FPCServer


FPCServer.DiskDrives Property

Returns a collection of disk-drive objects in this server.

Syntax

[ collFPCDiskDrives = ] FPCServer.DiskDrives

Possible Values

collFPCDiskDrives
Reference to the FPCDiskDrives collection.

The property is read-only.

Applies To

FPCServer


FPCServer.FirewallServiceStatus Property

Returns a Boolean value that indicates whether the Firewall service is running.

Syntax

[ bFirewallServiceStatus = ] FPCServer.FirewallServiceStatus

Possible Values

bFirewallServiceStatus
Boolean value indicating whether the Firewall service is running.

The property is read-only.

Applies To

FPCServer


FPCServer.FirewallServiceUpTime Property

Returns a DATE value that indicate the date since the Firewall service has worked properly.

Syntax

[ dUpTime = ] FPCServer.FirewallServiceUpTime

Possible Values

dUpTime
DATE value that indicates the date since the Firewall service has worked properly.

The property is read-only.

Applies To

FPCServer


FPCServer.FirewallSessions Property

Returns a collection of FPCFirewallSession objects in this server.

Syntax

[ collFPCFirewallSessions = ] FPCServer.FirewallSessions

Possible Values

collFPCFirewallSessions
Reference to the FPCFirewallSessions collection.

The property is read-only.

Applies To

FPCServer


FPCServer.ForwardProxyListenEntries Property

Returns a collection of FPCListenEntry objects.

Syntax

[ collFPCListenEntries = ] FPCServer.ForwardProxyListenEntries

Possible Values

collFPCListenEntries
Reference to the FPCListenEntries collection.

The property is read-only.

Applies To

FPCServer


FPCServer.FQDN Property

Returns the Fully Qualified Domain Name (FQDN) of the server.

Syntax

[ sFQDN = ] FPCServer.FQDN

Possible Values

sFQDN
String that specifies the FQDN.

The property is read-only.

Applies To

FPCServer


FPCServer.HttpViaHeaderAlias Property

Sets or retrieves the ViaHeaderAlias setting of the server, which the Web proxy adds to each HTTP response from this server.

Syntax

FPCServer.ViaHeaderAlias [ = sViaHeaderAlias ]

Possible Values

sViaHeaderAlias
String that specifies the via-header property of the server.

The property is read-write.

Applies To

FPCServer


FPCServer.IntraArrayAddress Property

Returns a reference to the returned key string.

Syntax

FPCServer.IntraArrayAddress [ = sIntraArrayAddress ]

Possible Values

sIntraArrayAddress
Reference to returned key string.

The property is read-write.

Applies To

FPCServer


FPCServer.LastModifiedTime Property

Returns a DATE data type that specifies the last modification time of the object.

Syntax

[ dLastModifiedTime = ] FPCServer.LastModifiedTime

Possible Values

dLastModifiedTime
Reference to a DATE data type.

The property is read-only.

Applies To

FPCServer


FPCServer.LoadFactor Property

Sets or retrieves the load factor of the server. A load factor is a relative number that assigns more traffic to servers that are able to handle more requests.

Syntax

FPCServer.LoadFactor [ = lLoadFactorRuleActions ]

Possible Values

lLoadFactor
Long value that specifies the load factor.

The property is read-write.

Applies To

FPCServer


FPCServer.Name Property

Returns the name of the server.

Syntax

[ sName = ] FPCServer.Name

Possible Values

sName
String that specifies the server name.

The property is read-only.

Applies To

FPCServer


FPCServer.ProductId Property

Returns the identifier (ID) of the product installed on this server.

Syntax

[ sProductId = ] FPCServer.ProductId

Possible Values

sProductId
String that specifies the product ID.

The property is read-only.

Applies To

FPCServer


FPCServer.ProductVersion Property

Returns the version of the server.

Syntax

[ sVersion = ] FPCServer.ProductVersion

Possible Values

sVersion
String that specifies the version of the server.

The property is read-only.

Applies To

FPCServer


FPCServer.RasPhoneBookEntries Property

Returns a collection of Remote Access Service (RAS) phone book entry names in this server.

Syntax

[ oFPCRasPhoneBookEntries = ] FPCServer.RasPhoneBookEntries

Possible Values

oFPCRasPhoneBookEntries
Reference to the FPCRasPhoneBookEntries collection.

The property is read-only.

Applies To

FPCServer


FPCServer.Refresh Method

Reads the server's information from persistent storage, discarding any changes to the server that were not saved.

Syntax

FPCServer.Refresh()

Applies To

FPCServer


FPCServer.RestartServices Method

Returns a collection of services that were previously stopped by the StopAllServices method and restarts those services.

Syntax

FPCServer.RestartServices()

Applies To

FPCServer


FPCServer.ReverseProxyListenEntries Property

Returns a collection of FPCListenEntry objects.

Syntax

[ collFPCListenEntries = ] FPCServer.ReverseProxyListenEntries

Possible Values

collFPCListenEntries
Reference to the FPCListenEntries collection.

The property is read-only.

Applies To

FPCServer


FPCServer.Save Method

Saves the server's configuration to persistent storage.

Syntax

FPCServer.Save()

Applies To

FPCServer


FPCServer.ScheduledContentDownloadServiceStatus Property

Returns a Boolean value that indicates the status of the scheduled content download service.

Syntax

[ bScheduledContentDownloadServiceStatus = ] FPCServer.ScheduledContentDownloadServiceStatus

Possible Values

bScheduledContentDownloadServiceStatus
A Boolean value that indicates the status of the scheduled content download service.

The property is read-only.

Applies To

FPCServer


FPCServer.ScheduledContentDownloadServiceUpTime Property

Returns a DATE value that indicates the date since the scheduled content download service has worked properly.

Syntax

[ dUpTime = ] FPCServer.ScheduledContentDownloadServiceUpTime

Possible Values

dUpTime
DATE value that indicates the date since the scheduled content download service has worked properly.

The property is read-only.

Applies To

FPCServer


FPCServer.ServerStatus Property

Returns a Boolean value indicating whether the server is functioning.

Syntax

[ bServerStatus = ] FPCServer.ServerStatus

Possible Values

bServerStatus
Boolean value indicating whether the server is functioning.

The property is read-only.

Applies To

FPCServer


FPCServer.SignaledAlerts Property

Returns a reference to the FPCSignaledAlerts collection.

Syntax

[ collFPCSignaledAlerts = ] FPCServer.SignaledAlerts

Possible Values

collFPCSignaledAlerts
A reference to the FPCSignaledAlerts collection.

The property is read-only.

Applies To

FPCServer


FPCServer.SSLClientCertificates Property

Returns an FPCSSLCertificates collection that represents Secure Sockets Layer (SSL) client certificates available on the server.

Syntax

[ collFPCSSLCertificates = ] FPCServer.SSLClientCertificates

Possible Values

collFPCSSLCertificates
Reference to an FPCSSLCertificates collection representing SSL client certificates available on the server.

The property is read-only.


FPCServer.SSLServerCertificates Property

Returns an FPCSSLCertificates collection representing Secure Sockets Layer (SSL) server certificates available on the server.

Syntax

[ collFPCSSLCertificates = ] FPCServer.SSLServerCertificates

Possible Values

collFPCSSLCertificates
Reference to an FPCSSLCertificates collection representing SSL server certificates available on the server.

The property is read-only.


FPCServer.StartFirewallService Method

Starts the Firewall service.

Syntax

FPCServer.StartFirewallService()

Applies To

FPCServer

See Also

FPCServer.StopFirewallService


FPCServer.StartScheduledContentDownloadService Method

Starts the scheduled content download service.

Syntax

FPCServer.StartScheduledContentDownloadService()

Applies To

FPCServer

See Also

FPCServer.StopScheduledContentDownloadService


FPCServer.StartWebProxyService Method

Starts the Web proxy service.

Syntax

FPCServer.StartWebProxyService()

Applies To

FPCServer

See Also

FPCServer.StopWebProxyService


FPCServer.StopAllServices Method

Returns a collection of services that were stopped on the current server.

Syntax

FPCServer.StopAllServices()

Applies To

FPCServer


FPCServer.StopFirewallService Method

Stops the Firewall service.

Syntax

FPCServer.StopFirewallService()

Applies To

FPCServer

See Also

FPCServer.StartFirewallService


FPCServer.StopScheduledContentDownloadService Method

Stops the scheduled content download service.

Syntax

FPCServer.StopScheduledContentDownloadService()

Applies To

FPCServer

See Also

FPCServer.StartScheduledContentDownloadService


FPCServer.StopWebProxyService Method

Stops the Web proxy service.

Syntax

FPCServer.StopWebProxyService()

Applies To

FPCServer

See Also

FPCServer.StartWebProxyService


FPCServer.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCServer object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCServer.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCServer


FPCServer.WebProxyServiceStatus Property

Returns a Boolean value that indicates whether the Web proxy is running.

Syntax

[ bWebProxyServiceStatus = ] FPCServer.WebProxyServiceStatus

Possible Values

bWebProxyServiceStatus
Boolean value indicating whether the Web proxy is running.

The property is read-only.

Applies To

FPCServer


FPCServer.WebProxyServiceUpTime Property

Returns a DATE value indicating the date since the Web proxy service has worked properly.

Syntax

[ dUpTime = ] FPCServer.WebProxyServiceUpTime

Possible Values

dUpTime
DATE value indicating the date since the Web proxy service has worked properly.

The property is read-only.

Applies To

FPCServer


FPCServer.WebSessions Property

Returns a collection of FPCWebSession objects in this server.

Syntax

[ collFPCWebSessions = ] FPCServer.WebSessions

Possible Values

collFPCWebSessions
Reference to the FPCWebSessions collection.

The property is read-only.

Applies To

FPCServer


FPCServers Collection

The FPCServers collection holds a group of FPCServer objects. This collection represents all the servers within the current array. All configurable settings within each ISA Server computer can be accessed by using objects within this collection.

It is a property of the FPCArray object.

Note to C++ Programmers

This collection implements the IFPCServers interface.

Note This collection holds only one server for the preliminary release. The server name is the same as that of the computer on which ISA is running.

Methods

The following table lists the methods of the FPCServers collection.

Method | Description
GetContainingServer | Returns the server containing the current computer.
Item | Retrieves the given FPCServer object from the collection.
Move | Moves a server from the source array to the current array.
Refresh | Reads all the FPCServer objects from persistent storage, discarding any changes to the objects that were not saved.
Remove | Removes a server from the collection.
Save | Saves the servers' configuration to persistent storage.

Properties

The following table lists the properties of the FPCServers collection

Property | Description
Count | Returns the number of server objects in the collection.
VendorParametersSets | Returns a reference to an object for storing and loading custom data into the FPCServers collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCServers.Count Property

Returns the number of server objects in the collection.

Syntax

[ iCount = ] FPCServers.Count

Possible Values

iCount
Integer value that specifies the number of FPCServer objects.

The property is read-only.

Applies To

FPCServers


FPCServers.GetContainingServer Method

Returns the server containing the current computer.

Syntax

[ oFPCServer = ] FPCServers.GetContainingServer()

Return Values

oFPCServer
Reference to the server that contains the current computer.

Example

The following piece of code retrieves the name of the containing ISA server by means of the GetContainingServer method.

Dim objFPC As New FPCLib.FPC
Dim ContainingServer As String
Dim objFPCArrays As FPCArrays
Dim objFPCArray As FPCArray
Dim objFPCServer As FPCServers
Set objFPCArrays = objFPC.Arrays
Set objFPCArray = objFPCArrays.CurrentArray
Set objFPCServers = objFPCArray.Servers
ContainingServer = objFPCServers.GetContainingServer.Name

Applies To

FPCServers


FPCServers.Item Method

Returns the given FPCServer object from the collection.

Syntax

[ vItem = ] FPCServers.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCServer. Otherwise:

• In C++, returns an error code and a null object.

• In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCServers


FPCServers.Move Method

Moves a server from the source array to the current array.

Syntax

FPCServers.Move( pSourceArray, vServer, bForced )

Parameters

pSourceArray
Required. Pointer to the source-array interface.
vServer
Required. Name or one-based index of the FPCServer object to move.
bForced
A Boolean value that specifies whether the move was forced.

Applies To

FPCServers

Remarks

The FPCServers collection represents a server array; you move a server from another array into the current array by using the Move method. This move will not be permanent until after the Save method is called and both the added array and the current array configuration are saved to persistent storage.


FPCServers.Refresh Method

Reads all the FPCServer objects from persistent storage, discarding any changes to the objects that were not saved.

Syntax

FPCServers.Refresh()

Applies To

FPCServers


FPCServers.Remove Method

Removes a server from the collection.

Syntax

FPCServers.Remove( iIndex )

Parameters

iIndex
Required. Name or one-based index of the FPCServer object to remove.

Remarks

The FPCServers collection represents a server array; you remove a server from an array by using the Remove method. This removal will not be permanent until after the Save method is called and the new array contents are saved to persistent storage.

Applies To

FPCServers


FPCServers.Save Method

Saves the servers' configuration to persistent storage.

Syntax

FPCServers.Save()

Applies To

FPCServers


FPCServers.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCServers collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCServers.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCServers


FPCSignaledAlert Object

The FPCSignaledAlert object represents a single signaled alert. This object is a member of the FPCSignaledAlerts collection.

The FPCSignaledAlert object is a run-time instance of an FPCAlert object. Signaled alerts appear under Real Time Monitoring in the ISA administration tool, and ISA alerts appear under Monitoring Configuration. An FPCAlert object contains alert configuration information, while the FPCSignaledAlert object contains both configuration and run-time information.

Note to C++ Programmers

This collection implements the IFPCSignaledAlert interface.

Methods

The following table lists the methods of the FPCSignaledAlert object.

Method | Description
Refresh | Reads the FPCSignaledAlert objects by means of a remote procedure call (RPC).
Reset | Resets the alert.

Properties

The following table lists the properties of the FPCSignaledAlert object.

Property | Description
ActiveSince | Retrieves a DATE value that specifies the date since the alert has been active.
AdditionalKey | Retrieves the additional key of the alert.
Description | Sets or retrieves the description of the alert.
EventGuid | Retrieves the event.
Name | Returns the name of the signaled alert.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSignaledAlert.ActiveSince Property

Retrieves a DATE value that specifies the date since the alert has been active.

Syntax

[ dActiveSince = ] FPCSignaledAlert.ActiveSince

Possible Values

dActiveSince
DATE value that specifies the date since the alert has been active.

The property is read-only.

Applies To

FPCSignaledAlert


FPCSignaledAlert.AdditionalKey Property

Retrieves the additional key of the alert.

Syntax

[ iAdditionalKey = ] FPCSignaledAlert.AdditionalKey

Possible Values

iAdditionalKey
Integer value that specifies the index of the additional key.

The property is read-only.

Applies To

FPCSignaledAlert


FPCSignaledAlert.Description Property

Sets or retrieves the description of the alert.

Syntax

[ Error! Bookmark not defined. = ] FPCSignaledAlert.Description

Possible Values

sDescription
String that specifies the description of the alert.

The property is read-only.

Applies To

FPCSignaledAlert


FPCSignaledAlert.EventGuid Property

Retrieves the event that triggered the alert.

Syntax

[ sGuid = ] FPCSignaledAlert.EventGuid

Possible Values

sGuid
String that specifies the event globally unique identifier (GUID).

The property is read-only.

Applies To

FPCSignaledAlert


FPCSignaledAlert.Name Property

Returns the name of the signaled alert.

Syntax

[ sName = ] FPCSignaledAlert.Name

Possible Values

sName
String that specifies the name of the signaled alert.

The property is read-only.

Applies To

FPCSignaledAlert


FPCSignaledAlert.Refresh Method

Reads all the properties by means of a remote procedure call (RPC).

Syntax

FPCSignaledAlert.Refresh()

Applies To

FPCSignaledAlert


FPCSignaledAlert.Reset Method

Resets the alert.

Syntax

FPCSignaledAlert.Reset()

Applies To

FPCSignaledAlert


FPCSignaledAlerts Collection

The FPCSignaledAlerts collection provides access to a group of FPCSignaledAlert objects. This object is a property of the FPCServer object.

Note to C++ Programmers

This collection implements the IFPCSignaledAlerts interface.

Methods

The following table lists the methods of the FPCSignaledAlerts collection.

Method | Description
Item | Retrieves the given FPCSignaledAlert object from the collection.
Refresh | Reads all the FPCSignaledAlert objects using remote procedure calls (RPCs).

Properties

The following table lists the properties of the FPCSignaledAlerts collection.

Property | Description
Count | Retrieves the number of FPCSignaledAlert objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSignaledAlerts.Count Property

Retrieves the number of FPCSignaledAlert objects in the collection.

Syntax

[ iCount = ] FPCSignaledAlerts.Count

Possible Values

iCount
Integer that specifies the number of FPCSignaledAlert objects.

The property is read-only.

Applies To

FPCSignaledAlerts


FPCSignaledAlerts.Item Method

Retrieves the given FPCSignaledAlert object from the collection.

Syntax

[ vItem = ] FPCSignaledAlerts.Item( vIndexOrEventGuid, vAdditionalKey )

Parameters

vIndexOrEventGuid
Required. Event globally unique identifier (GUID) or one-based index of the object to retrieve.
vAdditionalKey
Required if vIndex contains an event GUID, optional if vIndex contains one-based index. See FPCAlert.AdditionalKey.

Return Value

vItem
If successful, returns a reference to an object of type FPCSignaledAlert. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCSignaledAlerts


FPCSignaledAlerts.Refresh Method

Reads all the FPCSignaledAlert objects by means of a remote procedure call (RPC).

Syntax

FPCSignaledAlerts.Refresh()

Applies To

FPCSignaledAlerts


FPCSiteAndContentRule Object

The FPCSiteAndContentRule object represents a site and content rule. A site and content rule defines actions that will be taken when specific users attempt to access specific sites or content using ISA. ISA site and content rules allow you to define exactly which sites and content can be accessed by clients behind the ISA server. Site and content rules also determine when the rule is in effect by applying the rule during a specific schedule.

This object is a member of the FPCSiteAndContentRules collection.

Note to C++ Programmers

This object implements the IFPCSiteAndContentRule interface.

Methods

The following table lists the methods of the FPCSiteAndContentRule object.

Method | Description
Refresh | Reads all the rules from persistent storage, discarding any changes to the current rule that were not saved.
Save | Saves the rule configuration to persistent storage.
SetAppliesAlways | Sets the rule to apply always regardless of the ScheduleUsed property.
SetDestination | Sets the destinations to which the rule applies.
SetRedirectUrl | Sets the action to Redirect and sets the redirect URL and its code page.
SetSchedule | Sets the schedule to which the rule applies.

Properties

The following table lists the properties of the FPCSiteAndContentRule object.

Property | Description
Action | Sets or retrieves the type of action that this rule performs.
AppliesAlways | Retrieves whether the rule applies at all times.
AppliesToAccounts | Retrieves the collection of accounts for which the rule applies.
AppliesToContentMethod | Sets or retrieves the type of content to which the rule applies.
AppliesToDestination | Sets or retrieves the type of destination to which the rule applies.
AppliesToMethod | Sets or retrieves the method used for deciding rule applicability.
ClientAddressSetsExcluded | Retrieves the collection of client sets to which the rule does not apply.
ClientAddressSetsUsed | Retrieves the collection of client sets to which the rule applies.
ContentGroupsUsed | Retrieves the collection of content groups to which the rule applies.
Cpid | Retrieves the code page ID (Cpid) of a URL.
Description | Sets or retrieves the description of the rule.
DestinationSetUsed | Sets or retrieves the name of the FPCDestinationSet collection used to define the destination to which the rule applies.
Enabled | Sets or retrieves whether the rule is enabled.
Name | Sets or retrieves the name of the rule.
RedirectUrl | Sets or retrieves the URL to which to redirect requests when the Action property is set to the fpcRuleActionRedirect value of the FpcRuleActions enumeration.
ScheduleUsed | Sets or retrieves the name of the FPCScheduleTemplate object used to define the times when the rule applies.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCSiteAndContentRule object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSiteAndContentRule.Action Property

Sets or retrieves the type of action that this rule performs.

Syntax

FPCSiteAndContentRule.Action [ = RuleActions ]

Possible Values

RuleActions
Type of action. It can have a value of the FPCRuleActions enumerated type.

The property is read-write.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.AppliesAlways Property

Retrieves whether the rule applies at all times.

Syntax

[ bApplies = ] FPCSiteAndContentRule.AppliesAlways

Possible Values

bApplies
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Rule always applies to content.
FALSE | Rule does not apply to all content.

The property is read-only. It can be set to TRUE by calling the SetAppliesAlways method. Choosing a schedule by calling SetSchedule will set it to FALSE.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.AppliesToAccounts Property

Retrieves the collection of accounts to which the rule applies.

Syntax

[ collFPCAccounts = ] FPCSiteAndContentRule.AppliesToAccounts

Possible Values

collFPCAccounts
Reference to the FPCAccounts collection.

The property is read-only.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.AppliesToContentMethod Property

Sets or retrieves the type of content to which the rule applies.

Syntax

FPCSiteAndContentRule.AppliesToContentMethod [ = FpcAppliesToContentMethodType ]

Possible Values

FpcAppliesToContentMethodType
Type of content to which the rule applies. It can have a value of fpcAppliesToAllContent or fpcAppliesToSpecifiedContent from the FpcAppliesToContentMethod enumerated type.

The property is read-write.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.AppliesToDestination Property

Sets or retrieves the type of destination to which the rule applies.

Syntax

[ DestinationSelection = ] FPCSiteAndContentRule.AppliesToDestination

Possible Values

DestinationSelection
Type of destination to which the rule applies. It can have a value from the FpcDestinationSelection enumerated type.

The property is read-only. It can be set through the method SetDestination.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.AppliesToMethod Property

Sets or retrieves the method used for deciding rule applicability.

Syntax

FPCSiteAndContentRule.AppliesToMethod [ = AppliesToType ]

Possible Values

AppliesToType
Applicability method. It can have a value from the FpcAppliesToType enumeration.

The property is read-write.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.ClientAddressSetsExcluded Property

Retrieves the collection of client sets to which the rule does not apply.

Syntax

[ collFPCRefs = ] FPCSiteAndContentRule.ClientAddressSetsExcluded

Possible Values

collFPCRefs
Reference to the FPCRefs collection.

The property is read-only.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.ClientAddressSetsUsed Property

Retrieves the collection of client sets for which the rule applies.

Syntax

[ collFPCRefs = ] FPCSiteAndContentRule.ClientAddressSetsUsed

Possible Values

collFPCRefs
A reference to the FPCRefs collection.

The property is read-only.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.ContentGroupsUsed Property

Retrieves the collection of content groups to which the rule applies.

Syntax

[ collFPCRefs = ] FPCSiteAndContentRule.ContentGroupsUsed

Possible Values

collFPCRefs
A reference to the FPCRefs collection.

The property is read-only.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.Cpid Property

Retrieves the code page ID (Cpid) of the URL specified by the RedirectUrl property. The Cpid is useful if a URL string contains national characters that are not ANSI standard; for example, if a URL string contains Japanese characters.

Syntax

[ lCpid = ] FPCSiteAndContentRule.Cpid

Possible Values

lCpid
Long value that specifies the Cpid of a URL.

The property is read-only.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.Description Property

Sets or retrieves the description of the rule.

Syntax

FPCSiteAndContentRule.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the rule.

The property is read-write.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.DestinationSetUsed Property

Retrieves the name of the FPCRef object used to define the destination to which the rule applies.

Syntax

[ oFPCRef = ] FPCSiteAndContentRule.DestinationSetUsed

Possible Values

oFPCtRef
Reference to an FPCRef object.

The property is read-only. It can be set by using the SetDestination method.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.Enabled Property

Sets or retrieves whether the rule is enabled.

Syntax

FPCSiteAndContentRule.Enabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of two settings:
Setting | Meaning
TRUE | Rule is enabled.
FALSE | Rule is disabled.

The property is read-write.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.Name Property

Sets or retrieves the name of the rule.

Syntax

FPCSiteAndContentRule.Name [ = sName ]

Possible Values

sName
String that specifies the name.

The property is read-write.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.RedirectUrl Property

Sets or retrieves the URL to redirect requests to when the Action property is set to the fpcRuleActionRedirect value of the FpcRuleActions enumerated type.

Syntax

[ sURL = ] FPCSiteAndContentRule.RedirectUrl

Possible Values

sURL
String that specifies the URL.

The property is read-only. It can be set through the SetRedirectUrl method.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.Refresh Method

Reads all the rules from persistent storage, discarding any changes to the current rule that were not saved.

Syntax

FPCSiteAndContentRule.Refresh()

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.Save Method

Saves the rule configuration to persistent storage.

Syntax

FPCSiteAndContentRule.Save()

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.ScheduleUsed Property

Retrieves the name of an FPCRef object that is used to define the actual times when the rule applies.

Syntax

[ oFPCRef = ] FPCSiteAndContentRule.ScheduleUsed

Possible Values

oFPCRef
Reference to an FPCRef object.

The property is read-only. It can be set through the SetSchedule method.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.SetAppliesAlways Method

Sets the site and content rule, which is represented by the FPCSiteAndContentRule object, to apply at all times and on all days. The ScheduleUsed property returns the schedule that usually defines the actual times when this rule applies. This schedule becomes meaningless when the SetAppliesAlways method is used.

Syntax

FPCSiteAndContentRule.SetAppliesAlways()

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.SetDestination Method

Sets the destinations to which the rule applies.

Syntax

FPCSiteAndContentRule.SetDestination( DestType, sDestSet, ItemScope )

Parameters

DestType
Required. Defines the type of destinations. It can have a value of the FpcDestinationSelection enumerated type.
sDestSet
Optional. String that specifies the destination set to use. Needed when DestType is set to fpcDestinationSet.
ItemScope
Optional. Item scope. This can have a value from the FpcItemScope enumeration. when DestType is set to fpcDestinationSet, ItemScope defines the destination set as either an array policy or enterprise policy destination set.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.SetRedirectUrl Method

Sets the action to Redirect and sets the redirect URL and its code page.

Syntax

FPCSiteAndContentRule.SetRedirectUrl( sUrl, Cpid )

Parameters

sUrl
String value that specifies the URL to which to redirect.
Cpid
Optional. The code page for the URL string. Only used if DestType equals the fpcDestinationSet value of the FpcDestinationSelection enumerated type.

Applies To

FPCSiteAndContentRule

See Also

SetDestination


FPCSiteAndContentRule.SetSchedule Method

Sets the schedule to which the rule applies.

Syntax

FPCSiteAndContentRule.SetSchedule( sScheduleName, ItemScope )

Parameters

sScheduleName
String specifying the name of the schedule to which the rule applies.
ItemScope
The item scope. Defines whether the schedule being set is from the local collection of schedules (array scope) or from the enterprise collection of schedules. It can have a value from the FpcItemScope enumeration.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCSiteAndContentRule object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCSiteAndContentRule.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRules Collection

The FPCSiteAndContentRules collection provides access to a group of FPCSiteAndContentRule objects. An individual FPCSiteAndContentRule object represents a site and content rule. A site and content rule defines actions that will be taken when specific users attempt to access specific sites or content using the ISA server. ISA site and content rules allow you to define exactly which sites and content can be accessed by clients behind the ISA server. Site and content rules also determine when the rule is in effect by applying the rule during a specific schedule. The rules appear in this collection in order of their execution. The order can be modified by using the MoveUp and MoveDown methods.

The FPCSiteAndContentRules collection is a property of the FPCArrayPolicy object.

Note to C++ Programmers

This collection implements the IFPCSiteAndContentRules interface.

Methods

The following table lists the methods of the FPCSiteAndContentRules collection.

Method | Description
Add | Creates a new FPCSiteAndContentRule object in the collection and returns a reference to it.
Item | Retrieves the given FPCSiteAndContentRule object from the collection.
Refresh | Reads all the rules from persistent storage, discarding any changes to the current rules that were not saved.
Remove | Removes a site and content rule from the collection.
Save | Saves all the rules in the collection to persistent storage.

Properties

The following table lists the properties of the FPCSiteAndContentRules collection.

Property | Description
Count | Retrieves the number of FPCSiteAndContentRule objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data in the FPCSiteAndContentRules collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSiteAndContentRules.Add Method

Creates a new FPCSiteAndContentRule object in the collection and returns a reference to it. The name must be unique; if this method is called with an existing name, Add will fail.

Syntax

[ oFPCSiteAndContentRule = ] FPCSiteAndContentRules.Add( sName )

Parameters

sName
Required. String that specifies the name of the new rule.

Return Value

oFPCSiteAndContentRule
Reference to an FPCSiteAndContentRule object.

Applies To

FPCSiteAndContentRules


FPCSiteAndContentRules.Count Property

Retrieves the number of FPCSiteAndContentRule objects in the collection.

Syntax

[ iCount = ] FPCSiteAndContentRules.Count

Possible Values

iCount
Integer value that specifies the number of rule objects.

The property is read-only.

Applies To

FPCSiteAndContentRules


FPCSiteAndContentRules.Item Method

Retrieves a given FPCSiteAndContentRule object from the collection.

Syntax

[ vItem = ] FPCSiteAndContentRules.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCSiteAndContentRule. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCSiteAndContentRules


FPCSiteAndContentRules.Refresh Method

Reads all the rules from persistent storage, discarding any changes to the current rules that were not saved.

Syntax

FPCSiteAndContentRules.Refresh()

Applies To

FPCSiteAndContentRules


FPCSiteAndContentRules.Remove Method

Removes an FPCSiteAndContentRule object from the collection.

Syntax

FPCSiteAndContentRules.Remove( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to remove.

Applies To

FPCSiteAndContentRules


FPCSiteAndContentRules.Save Method

Saves all the rules in the collection to persistent storage.

Syntax

FPCSiteAndContentRules.Save()

Applies To

FPCSiteAndContentRules


FPCSiteAndContentRules.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCSiteAndContentRules collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCSiteAndContentRules.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCSiteAndContentRules


FPCSnapinNode Object

The FPCSnapinNode object is used to extend the ISA Server administration tool.For more information see Extending the ISA Administration Tool.

Note to C++ Programmers

This object implements the IFPCSnapinNode interface. It can be retrieved by querying the IDataObject interface of the ISA node that is to be extended:

DataObject->QueryInterface(IID_IFPCSnapinNode)

Properties

The following table lists the properties of the FPCSnapinNode object.

Property | Description
ComRoot | Retrieves the FPC root object.
CurrentObject | Retrieves the object that you are extending.
ParentArray | Retrieves the array under which you create an extension.
ParentPolicy | Retrieves the FPCEnterprisePolicy under which you create an extension.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSnapinNode.ComRoot Property

Retrieves the FPC root object.

Syntax

[ Root = ] FPCSnapinNode.ComRoot( Root )

Possible Values

Root
The FPC root object.

The property is read-only.

Applies To

FPCSnapinNode


FPCSnapinNode.CurrentObject Property

Retrieves the object that you are extending. Through this property you can access FPCVendorParametersSets.

Syntax

[ Object = ] FPCSnapinNode.CurrentObject( Object )

Possible Values

Object
The current object.

The property is read-only.

Applies To

FPCSnapinNode


FPCSnapinNode.ParentArray Property

Retrieves the array under which you are creating an extension.The ParentArray property is an FPCArray object as exposed through the ISA administration COM object model.

Syntax

[ Array = ] FPCSnapinNode.ParentArray( Array )

Possible Values

Array
The parent array.

The property is read-only.

Applies To

FPCSnapinNode


FPCSnapinNode.ParentPolicy Property

Retrieves the FPCEnterprisePolicy under which you create an extension. The ParentPolicy property is an FPCEnterprisePolicy object as exposed through the ISA administration COM object model.

Syntax

[ Policy = ] FPCSnapinNode.ParentPolicy( Policy )

Possible Values

Policy
The enterprise policy.

The property is read-only.

Applies To

FPCSnapinNode


FPCSSLCertificate Object

The FPCSSLCertificate object represents an SSL server certificate stored on an ISA server computer. The FPCSSLCertificate provides read-only access to certificate information..

This object is a member of the FPCSSLCertificates collection.

Note to C++ Programmers

This object implements the IFPCSSLCertificate interface.

Properties

The following table lists the properties of the FPCSSLCertificate object.

Property | Description
ExpirationDate | Retrieves the certificate's expiration date.
FriendlyName | Retrieves the certificate's friendly name.
Hash | Retrieves the certificate's hash value
IssuedBy | Retrieves the name of the entity that issued the certificate.
IssuedTo | Retrieves the entity to whom the certificate was issued.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSSLCertificate.ExpirationDate Property

Retrieves the expiration date of the certificate.

Syntax

[ Date = ] FPCSSLCertificate.ExpirationDate

Possible Values

Date
The expiration date.

The property is read-only.

Applies To

FPCSSLCertificate


FPCSSLCertificate.FriendlyName Property

Retrieves the friendly name of the certificate.

Syntax

[ sFriendlyName = ] FPCSSLCertificate.FriendlyName

Possible Values

sFriendlyName
A string that specifies the friendly name of the certificate.

The property is read-only.

Applies To

FPCSSLCertificate


FPCSSLCertificate.Hash Property

Retrieves the hash value of the certificate.

Syntax

[ Hash = ] FPCSSLCertificate.Hash

Possible Values

Hash
The hash value.

The property is read-only.

Applies To

FPCSSLCertificate


FPCSSLCertificate.IssuedBy Property

Retrieves the name of the entity that issued the certificate.

Syntax

[ sIssuedBy = ] FPCSSLCertificate.IssuedBy

Possible Values

sIssuedBy
A string that specifies the entity that issued the certificate.

The property is read-only.

Applies To

FPCSSLCertificate


FPCSSLCertificate.IssuedTo Property

Retrieves the name of the entity to whom the certificate was issued.

Syntax

[ IssuedTo = ] FPCSSLCertificate.IssuedTo

Possible Values

sIssuedTo
A string that specifies the entity to which the certificate was issued.

The property is read-only.

Applies To

FPCSSLCertificate


FPCSSLCertificates Collection

Represents a collection of FPCSSLCertificate objects.

Note to C++ Programmers

This collection implements the IFPCSSLCertificates interface.

Note

If the contents of this colleciton change, the Web proxy (w3proxy) service must be restarted. To stop and restart the w3proxy service use the FPCArray.SendRestartNotification Method.

Methods

The following table lists the methods of the FPCSSLCertificate object.

Method | Description
Item | Retrieves the given FPCSSLCertificate object for the collection.
Refresh | Refreshes the FPCSSLCertificates collection to include certificates that may have been added to the server.

Properties

The following table lists the properties of the FPCSSLCertificate object.

Property | Description
Count | Returns the number of FPCSSLCertificate objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSSLCertificates.Count Property

Returns the number of FPCSSLCertificate objects in the collection.

Syntax

[ iCount = ] FPCSSLCertificates.Count

Possible Values

lCount
Long value that specifies the number of FPCSSLCertificate objects.

The property is read-only.

Applies To

FPCSSLCertificates


FPCSSLCertificates.Item Method

Retrieves the given FPCSSLCertificate object for the collection.

[ vItem = ] FPCSSLCertificates.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

If successful, returns a reference to an object of type FPCSSLCertificate. Otherwise:

  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCSSLCertificates


FPCSSLCertificates.Refresh Method

Reads the object from persistent storage, to include certificates that may have been added to the server.

Note

Certificates are not added by using the FPC objects..

Syntax

FPCSSLCertificates.Refresh()

Applies To

FPCSSLCertificates


FPCVendorParametersSet Object

The FPCVendorParametersSet object is used to set and return any vendor-specific data. FPCVendorParametersSet objects are used to integrate third-party extensions into ISA. Most ISA objects that are used programmatically have a VendorParametersSets property and can therefore be extended.

This object is used to store data that is defined as {name, value} pairs using the Value property. The following example stores a property named x having a value of 1:

FPCVendorParametersSet.Value("x") = 1

The phrase Value("x") will return the value.

This object is a member of the FPCVendorParametersSets collection.

Note to C++ Programmers

This object implements the IFPCVendorParametersSet interface.

Methods

The following table lists the methods of the FPCVendorParametersSet object.

Method | Description
Refresh | Reads the object from persistent storage, discarding any changes to the object that were not saved.
RemoveValue | The RemoveValue method of the FPCVendorParametersSet object removes the given value from the set.
Save | Saves the object's configuration to persistent storage.
WaitForChanges | For use in C and C++ programming only; registers to wait for an event indicating that the FPCVendorParametersSet context has changed.

Properties

The following table lists the properties of the FPCVendorParametersSet object.

Property | Description
AllNames | Returns all the names of the parameters set.
Name | Sets or returns the name of the parameters set.
Value | Sets or returns the value associated with the given name.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCVendorParametersSet.AllNames Property

Returns all the names of the parameters set.

Syntax

[ pItem = ]FPCVendorParametersSet.AllNames

Possible Values

pItem
Pointer to an array of strings.

The property is read-only.

Remarks

The AllNames property returns a list of all the names of user-defined properties stored through the Value property.

For example, the following uses the Value property to store two user-defined values, "1" and "2":

obj.Value("x") = 1
obj.Value("y") = 2

If the AllNames property is used now, it returns an array of strings containing the strings "x" and "y".

Applies To

FPCVendorParametersSet


FPCVendorParametersSet.Name Property

Sets or retrieves the name of the parameters set.

Syntax

FPCVendorParametersSet.Name [ = sName ]

Possible Values

sName
String that specifies the parameters set name.

The property is read-write.

Applies To

FPCVendorParametersSet


FPCVendorParametersSet.Refresh Method

Reads the object from persistent storage, discarding any changes to the object that were not saved.

Syntax

FPCVendorParametersSet.Refresh()

Applies To

FPCVendorParametersSet


FPCVendorParametersSet.RemoveValue Method

Removes the given value from the set.

Syntax

FPCVendorParametersSet.RemoveValue( sValue )

Parameters

sValue
String that specifies the value to remove.

Applies To

FPCVendorParametersSet


FPCVendorParametersSet.Save Method

Saves the object's configuration to persistent storage.

Syntax

FPCVendorParametersSet.Save()

Applies To

FPCVendorParametersSet


FPCVendorParametersSet.Value Property

Sets or returns the value associated with the given name.

Syntax

FPCVendorParametersSet.Value (Name)[ = Value ]

Possible Values

Name
Specifies the parameter name for which to retrieve the value. The name can be of almost any type and is not necessarily a string.

The property is read-write.

Remarks

The FPCVendorParametersSet object is used to store data that is defined as {name, value} pairs using the Value property. The following example stores a property named x having a value of 1:

FPCVendorParametersSet.Value("x") = 1

The phrase Value("x") will return the value.

The Value property is also the default property. The following examples are equivalent:

obj.Value("x)
obj("x")

Applies To

FPCVendorParametersSet


FPCVendorParametersSet.WaitForChanges Method

Registers to wait for an event indicating that the contents of the FPCVendorParametersSet object have changed.

Note This method can only be used in C and C++ programming languages. It cannot be used with DCOM.

Syntax

FPCVendorParametersSet.WaitForChanges( hEvent )

Parameters

hEvent
An event that will be signaled whenever the storage content of the FPCVendorParametersSet object has changed.

Remarks

This method also allows you to define event handlers in Visual Basic in the format:

private sub objectname_OnChange
end sub

In the following example, code executes when the FPCVendorParametersSet object defined as pd changes:

Dim FPC As New FPC
Dim WithEvents pd As FPCVendorParametersSet
Private Sub Start_Click()
  Set pd = FPC.Arrays(1).VendorParametersSets(1)

End Sub

Private Sub pd_OnChange()
  pd.Refresh
  MsgBox "pd_OnChange - user is:" & pd("UserName")
End Sub

Applies To

FPCVendorParametersSet


FPCVendorParametersSets Collection

The FPCVendorParametersSets collection is used to access the collection of FPCVendorParametersSet objects. Most ISA objects have a VendorParametersSets property that is a reference to this FPCVendorParametersSets collection. A third party can use this collection to associate private sets of configuration information with the object being extended. All objects that have a VendorParametersSets property are extensible.

Each set is identified by a globally unique identifier (GUID) that is provided to the Add method when a new set is created.

Using the FPCVendorParametersSets collection also permits a third party to take advantage of the backup-and-restore capabilities of ISA. Any data stored in this collection is backed up with the rest of the objects whenever a backup is done. The third-party data is also saved to the Active Directory when available by the Save method of this collection, or whenever the Save method of the object being extended is called. You don't need to write code in order to read and write directly from the Registry or the Active Directory when using this collection because reading from and writing to storage are taken care of by the Save and Refresh methods.

Note to C++ Programmers

This collection implements the IFPCVendorParametersSets interface.

Methods

The following table lists the methods of the FPCVendorParametersSets collection.

Method | Description
Add | Creates a new FPCVendorParametersSet object, inserts it into the collection, and returns a reference to it.
Item | Returns the given FPCVendorParametersSet object from the collection.
Refresh | Reads all the FPCVendorParametersSet objects from persistent storage, discarding any changes to the objects that were not saved.
Remove | Removes a parameters set from the collection.
Save | Saves the configuration of all FPCVendorParametersSet objects to persistent storage.

Properties

The following table lists the properties of the FPCVendorParametersSets collection.

Property | Description
Count | Returns the number of FPCVendorParametersSet objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCVendorParametersSets.Add Method

Creates a new FPCVendorParametersSet object, inserts it into the collection, and returns a reference to it.

Syntax

[ oFPCVendorParametersSet = ] FPCVendorParametersSets.Add( sGUID, bEncrypted )

Parameters

sGUID
Required. String that specifies the GUID of the new object.
bEncrypted
Optional. A Boolean expression. If TRUE, the data will be saved in an encrypted form, and only calls under the local system account will be able to read the data. If FALSE, the data will not be saved in encrypted form.

Return Values

oFPCVendorParametersSet
Returns a reference to the FPCVendorParametersSet object.

Remarks

The GUID must be in the following format:

"{482acfde-0a4a-479b-b856-3206a1fe2a6c}"

Applies To

FPCVendorParametersSets


FPCVendorParametersSets.Count Property

Returns the number of parameters set objects in the collection.

Syntax

[ iCount = ] FPCVendorParametersSets.Count

Possible Values

iCount
Integer value that specifies the number of FPCVendorParametersSet objects.

The property is read-only.

Applies To

FPCVendorParametersSets


FPCVendorParametersSets.Item Method

Returns the given FPCVendorParametersSet object from the collection.

Syntax

[ vItem = ] FPCVendorParametersSets.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

If successful, returns a reference to an object of type FPCVendorParametersSet. Otherwise:

  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCVendorParametersSets


FPCVendorParametersSets.Refresh Method

Reads all the FPCVendorParametersSet objects from persistent storage, discarding any changes to the objects that were not saved.

Syntax

FPCVendorParametersSets.Refresh()

Applies To

FPCVendorParametersSets


FPCVendorParametersSets.Remove Method

Removes a parameters set from the collection.

Syntax

FPCVendorParametersSets.Remove( iIndex )

Parameters

iIndex
Required. Name or one-based index of the FPCVendorParametersSet object to remove.

Applies To

FPCVendorParametersSets


FPCVendorParametersSets.Save Method

Saves the configuration of all FPCVendorParametersSet objects to persistent storage.

Syntax

FPCVendorParametersSets.Save()

Applies To

FPCVendorParametersSets


FPCWebBrowserClientConfig Object

The FPCWebBrowserClientConfig object represents the browser configuration, and is a property of the FPCProxyClientConfig object. You can set a client's Web browser settings so that a client will work with the ISA Web proxy service. That configuration is represented by FPCWebBrowserClientConfig. This object generates a configuration file for clients that use the ISA server as a Web proxy service. This configuration file will be used by the ISA client setup to configure the browsers on users' computers.

Note to C++ Programmers

This object implements the IWebBrowserClientConfig interface.

Methods

The following table lists the methods of the FPCWebBrowserClientConfig object.

Method | Description
Refresh | Reads the browser configuration information from persistent storage, discarding any changes to the current object that were not saved.
Save | Saves the browser configuration information to the persistent storage.
SetBrowserConfigScript | Sets whether the default or custom script is used.

Properties

The following table lists the properties of the FPCWebBrowserClientConfig object.

Property | Description
AutoScript | Returns a reference to the FPCClientAutoScript object.
BrowserConfigAutoDetect | Specifies whether to automatically detect proxy-server settings or automatic configuration settings.
BrowserConfigEnabled | Specifies whether the ISA Server client installation will affect the client's browser settings.
BrowserConfigScriptAddress | Address (URL) or file name of the file that will be used to configure the browser.
BrowserConfigScriptEnabled | Specifies whether the browser will use the information in the configuration file.
BrowserConfigScriptFlag | Sets whether the browser configuration uses a default script or a custom script.
ServerOrArrayName | Sets or retrieves the name of the proxy server. This name is translated by the Domain Name System (DNS) and can point to multiple proxy servers.
VendorParametersSets | Returns a reference to an object for storing and loading of custom data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebBrowserClientConfig.AutoScript Property

Returns a reference to an FPCClientAutoScript object.

Syntax

[ oFPCClientAutoScript = ] FPCWebBrowserClientConfig.AutoScript

Return Values

oFPCClientAutoScript
Returns a reference to an FPCClientAutoScript object.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.BrowserConfigAutoDetect Property

Specifies whether to automatically detect proxy-server settings or automatic configuration settings.

Syntax

[ bAutoDetect = ] FPCWebBrowserClientConfig.BrowserConfigAutoDetect

Return Values

bAutoDetect
Boolean value that specifies whether the settings will be automatically detected.

The property is read-write.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.BrowserConfigEnabled Property

Specifies whether the ISA Server client installation will affect the client's browser settings.

Syntax

[ bEnabled = ] FPCWebBrowserClientConfig.BrowserConfigEnabled

Possible Values

bEnabled
Boolean value that determines if affect on browser is enabled.

The property is read-write.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.BrowserConfigScriptAddress Property

Address (URL) or file name of the file that will be used to configure the browser.

Syntax

[ sAddress = ] FPCWebBrowserClientConfig.BrowserConfigEnabled

Return Values

sAddress
A string that specifies the address or name of the file.
This property is read-only.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.BrowserConfigScriptEnabled Property

Specifies whether the browser will use the information in the configuration file.

Syntax

[ bEnabled = ] FPCWebBrowserClientConfig.BrowserConfigScriptEnabled

Return Values

bEnabled
Boolean value that specifies whether the browser will use the information in the configuration file.

The property is read-write.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.BrowserConfigScriptFlag Property

Sets whether the browser configuration uses a default script or a custom script.

Syntax

[ ConfigScript = ] FPCWebBrowserClientConfig.BrowserConfigScriptFlag

Return Values

ConfigScript
A flag that sets whether the default or custom script is used. Can have a value of either fpcBrowserDefaultScript, or fpcBrowserCustomScript from the FpcBrowserConfigScriptFlag enumerated type.

The property is read-only.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.Port Property

Sets or retrieves the port to which the proxy server (or servers, in the case of an array) listens for requests.

Syntax

FPCWebBrowserClientConfig.Port [ = iPort ]

Possible Values

iPort
Integer value that specifies the port to which the proxy server listens for requests.

The property is read-write.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.Refresh Method

Reads the browser configuration information from persistent storage, discarding any changes to the current object that were not saved.

Syntax

FPCWebBrowserClientConfig.Refresh()

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.Save Method

Saves the browser configuration information to persistent storage.

Syntax

FPCWebBrowserClientConfig.Save()

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.ServerOrArrayName Property

Sets or retrieves the name of the proxy server. This name is translated by the Domain Name System (DNS) and can point to multiple proxy servers.

Syntax

FPCWebBrowserClientConfig.ServerOrArrayName [ = sName ]

Possible Values

sName
String that specifies the name of the proxy server.

The property is read-write.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.SetBrowserConfigScript Method

Sets whether the default or custom script is used.

Syntax

FPCWebBrowserClientConfig.SetBrowserConfigScript( ConfigScript, sScript )

Parameters

ConfigScript
Can have a value from the FpcBrowserConfigScriptFlag enumerated type.
sScript
String that identifies a configuration script.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data.The VendorParametersSets property allows third-party extensions to be integrated into ISA.

Syntax

[ collFPCVendorParametersSets = ] FPCWebBrowserClientConfig.VendorparametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCWebBrowserClientConfig


FPCWebFilter Object

The FPCWebFilter object represents a single Web (ISAPI) filter that is registered to extend the ISA Web proxy service. Web filters are dynamic-link libraries (DLLs) that are loaded when the ISA Web proxy service is started, and stay in memory until the service shuts down. Once loaded, Web filters can be configured to receive a number of special filter-event notifications. These filter-event notifications occur with each HTTP request that the ISA Web proxy service receives and with each response returned through the ISA Web proxy by an external Web server.

This object is a member of the FPCWebFilters collection.

Note to C++ Programmers

This object implements the IFPCWebFilter interface.

Note

When you've made and saved Web filter configuration changes the Web proxy (w3proxy) service must be restarted in order for your change to take effect. To stop and restart the w3proxy service use the FPCArray.SendRestartNotification Method.

Methods

The following table lists the methods of the FPCWebFilter object.

Method | Description
Refresh | Reads the filter's private data from persistent storage.
Save | Saves the filter's private data to persistent storage.

Properties

The following table lists the properties of the FPCWebFilter object.

Property | Description
Description | Sets or retrieves the vendor-supplied description of the filter.
Enabled | Sets or retrieves whether the filter is enabled.
FilterDirection | Sets or retrieves the direction of the filter.
Guid | Retrieves the globally unique identifier (GUID) that identifies the filter. The vendor of the filter provides the GUID.
Name | Sets or retrieves the vendor-supplied name of the filter.
Order | Retrieves the filter's order.
Priority | Sets or retrieves the filter's priority.
RelativePath | Sets or retrieves the filter dynamic-link library DLL path relative to ISA-install-dir\isapi.
Vendor | Sets or retrieves the name of the vendor of the filter.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCWebFilter object's storage.
Version | Sets or retrieves the vendor-supplied version of the filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebFilter.Description Property

Sets or retrieves the vendor-supplied description of the filter.

Syntax

FPCWebFilter.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the vendor-supplied description.

The property is read-write.

Applies To

FPCWebFilter


FPCWebFilter.Enabled Property

Sets or retrieves whether the filter is enabled.

Syntax

FPCWebFilter.Enabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these sessions:
Setting | Meaning
TRUE | Filter is enabled.
FALSE | Filter is disabled.

The property is read-write.

Applies To

FPCWebFilter


FPCWebFilter.FilterDirection Property

Retrieves whether the filter operates in reverse, forward, or both directions.

Syntax

[ FilterDirection = ] FPCWebFilter.FilterDirection

Return Value

FilterDirection
Returns a value from the FpcFilterDirection enumeration.

The property is read only.

Applies To

FPCWebFilter


FPCWebFilter.Guid Property

Retrieves the globally unique identifier (GUID) that identifies the filter. The vendor of the filter provides the GUID.

Syntax

[ sGuid = ] FPCWebFilter.Guid

Possible Values

sGuid
String that specifies the GUID for the plug-in.

The property is read-only.

Applies To

FPCWebFilter


FPCWebFilter.Name Property

Sets or retrieves the vendor-supplied name of the filter.

Syntax

FPCWebFilter.Name [ = sName ]

Possible Values

sName
String that specifies the vendor-supplied name.

The property is read-write.

Applies To

FPCWebFilter


FPCWebFilter.Order Property

Retrieves the filter's order.

Syntax

[ iOrder = ] FPCWebFilter.Order

Possible Values

iOrder
Integer value that specifies the order of the filter.

The property is read-only.

Applies To

FPCWebFilter


FPCWebFilter.Priority Property

Sets or retrieves the priority of the filter.

Syntax

FPCWebFilter.Priority [ = FPCFilterPriority ]

Possible Values

FpcFilterPriority
Filter priority. Can have a value of fpcFilterPriority_Low, fpcFilterPriority_Medium, or fpcFilterPriority_High from the FpcFilterPriority enumerated type.

The property is read-write.


FPCWebFilter.Refresh Method

Reads the filter's private data from persistent storage.

Syntax

FPCWebFilter.Refresh()

Applies To

FPCWebFilter


FPCWebFilter.RelativePath Property

Sets or retrieves the filter DLL path relative to ISA-install-dir\isapi.

Syntax

FPCWebFilter.RelativePath [ = sPath ]

Possible Values

sPath
String that specifies the relative path.

The property is read-write.

Applies To

FPCWebFilter


FPCWebFilter.Save Method

Saves the filter's private data to persistent storage.

Syntax

FPCWebFilter.Save()

Applies To

FPCWebFilter


FPCWebFilter.Vendor Property

Sets or retrieves the name of the vendor of the filter.

Syntax

FPCWebFilter.Vendor [ = sVendor ]

Possible Values

sVendor
String that specifies the vendor's name.

The property is read-write.

Applies To

FPCWebFilter


FPCWebFilter.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCWebFilter object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCWebFilter.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCWebFilter


FPCWebFilter.Version Property

Sets or retrieves the vendor-supplied version of the filter.

Syntax

FPCWebFilter.Version [ = sVersion ]

Possible Values

sVersion
String that specifies the vendor-supplied version.

The property is read-write.

Applies To

FPCWebFilter


FPCWebFilters Collection

The FPCWebFilters collection provides access to a group of FPCWebFilter objects.

This object is a member of the FPCPolicyElements object.

Note to C++ Programmers

This collection implements the IFPCWebFilters interface.

Note When you've made and saved Web filter configuration changes the Web proxy (w3proxy) service must be restarted in order for your change to take effect. To stop and restart the w3proxy service use the FPCArray.SendRestartNotification Method.

Methods

The following table lists the methods of the FPCWebFilters collection.

Method | Description
Add | Adds a new FPCWebFilter object to the collection.
Item | Retrieves the given FPCWebFilter object from the collection.
MoveDown | Moves the given filter one step down in the filter order.
MoveUp | Moves the given filter one step up in the filter order.
Refresh | Reads all the Web (ISAPI) filters objects from persistent storage.
Remove | Removes a plug-in object from the collection.
Save | Saves the filters data to persistent storage.

Properties

The following table lists the properties of the FPCWebFilters collection.

Property | Description
Count | Retrieves the number of Web filters in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading of custom data into the collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebFilters.Add Method

Adds a new FPCWebFilter object.

Syntax

[ oFPCWebFilter = ] FPCWebFilter .Add( sGuid, sName, sRelativePath, FpcFilterPriority )

Parameters

sGuid
Required. String that specifies the GUID of the new plug-in.
sName
Required. String that specifies the display name of the new plug-in.
sRelativePath
Required. String that specifies the path of the filter DLL relative to ISA-install-dir\isapi.
FpcFilterPriority
Filter priority. Can have a value from the FpcFilterPriority enumerated type.

Return Value

oFPCWebFilter
Returns a reference to the new FPCWebFilter object.

Applies To

FPCWebFilters

See Also

FPCWebFilter


FPCWebFilters.Count Property

Retrieves the number of Web (ISAPI) filters in the collection.

Syntax

[ iCount = ] FPCWebFilters.Count

Possible Values

iCount
Integer value that specifies the number of filter objects.

The property is read-only.

Applies To

FPCWebFilters

See Also

FPCWebFilter


FPCWebFilters.Item Method

Retrieves the given FPCWebFilter object from the collection.

Syntax

[ vItem = ] FPCWebFilters.Item( vIndex )

Parameters

vIndex
Required. GUID or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCWebFilter. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCWebFilters

See Also

FPCWebFilter


FPCWebFilters.MoveDown Method

Moves the given filter one step down in the filter order .

Syntax

FPCWebFilters.MoveDown( iIndex )

Parameters

iIndex
Required. Index (current order) of the filter to move down in the filter order.

Applies To

FPCWebFilters

See Also

MoveUp


FPCWebFilters.MoveUp Method

Moves the given filter one step up in the filter order.

Syntax

FPCWebFilters.MoveUp( iIndex )

Parameters

iIndex
Required. Index (current order) of the filter to move up in the filter order.

Applies To

FPCWebFilters

See Also

MoveDown


FPCWebFilters.Refresh Method

Reads all the Web (ISAPI) filters objects from persistent storage.

Syntax

FPCWebFilters.Refresh()

Applies To

FPCWebFilters


FPCWebFilters.Remove Method

Removes a plug-in object from the collection.

Syntax

FPCWebFilters.Remove( vIndex )

Parameters

vIndex
Required. GUID or one-based index of the object to remove.

Applies To

FPCWebFilters

See Also

FPCWebFilter


FPCWebFilters.Save Method

Saves the filter data to persistent storage.

Syntax

FPCWebFilters.Save()

Applies To

FPCWebFilters


FPCWebFilters.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into storage.

Syntax

[ collFPCVendorParametersSets = ] FPCWebFilters.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCWebFilters


FPCWebProxy Object

The FPCWebProxy object defines Web proxy authentication attributes. You can use this object to determine whether the Web proxy is set to always authenticate client requests to the server, and to determine the authentication type.

The FPCWebProxy object is a property of the FPCArrayPolicy object.

Note to C++ Programmers

This object implements the IFPCWebProxy interface.

Methods

The following table lists the methods of the FPCWebProxy object.

Method | Description
Refresh | Reads the object's configuration information from the Web proxy service using a remote procedure call (RPC), discarding any changes to the current configuration that were not saved.
Save | Saves all the object's data to persistent storage.

Properties

The following table lists the properties of the FPCWebProxy object.

Property | Description
AutoDiscoveryPort | Sets or retrieves the port to bind to if EnableAutoDiscovery is TRUE.
CARPNameSystem | Sets or retrieves whether CARP uses a DNS or WINS name system
EnableAutoDiscovery | Sets or retrieves whether the Web proxy binds to a specified port on all internal interfaces, and returns the routing script as a response to a wpad.dat request.
IncomingWebRequests | Returns a reference to the FPCListenEntries collection.
LoadSize | Not supported in this release.
OutgoingWebRequests | Returns a reference to the FPCListenEntries collection.
TunnelPortRanges | Retrieves a reference to an FPCProxyTunnelPortRanges collection.
UpstreamResolveSystem | Sets or retrieves whether a downstream server will use DNS or WINS information provided by an upstream server.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebProxy.AutoDiscoveryPort Property

Sets or retrieves the port to bind to if the EnableAutoDiscovery property is TRUE.

Syntax

FPCWebProxy.AutoDiscoveryPort [= lport ]

Possible Values

lport
Long value that specifies the port to bind to if EnableAutoDiscovery is TRUE.

The property is read-write.

Applies To

FPCWebProxy


FPCWebProxy.CARPNameSystem Property

Sets or retrieves whether a web proxy computer uses a Domain Name System (DNS) or Windows Internet Name Service (WINS) name system. This is important because some computers do not have WINS names, and will not work in CARP if you don't enable DNS name use.

Syntax

FPCWebProxy.CARPNameSystem [= FpcNameSystem ]

Possible Values

FpcNameSystem
The name system. It can have a value of fpc_NameSystem_DNS or fpc_NameSystem_WINS from the FpcNameSystem enumerated type.

The property is read-write.

Applies To

FPCWebProxy


FPCWebProxy.EnableAutoDiscovery Property

Sets or retrieves whether the Web proxy binds to a specified port on all internal interfaces, and returns the routing script as a response to a wpad.dat request.

Syntax

FPCWebProxy.EnableAutoDiscovery [= bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | The Web proxy binds to port 80 on all local interfaces.
FALSE | The Web proxy does not bind to port 80 on all local interfaces.

The property is read-write.

Applies To

FPCWebProxy


FPCWebProxy.IncomingWebRequests Property

Returns a reference to a FPCWebRequestConfiguration object. The FPCWebRequestConfiguration object provides access to the properties of forward proxy and reverse proxy.

Syntax

[ oFPCProxyListenConfig = ] FPCWebProxy.IncomingWebRequests

Possible Values

oFPCProxyListenConfig
Returns a reference to the FPCWebRequestConfiguration object.

The property is read-only.

Applies To

FPCWebProxy


FPCWebProxy.LoadSize Property

Not supported in this release.

Syntax

FPCWebProxy.LoadSize [= FpcLoadSize ]

Possible Values

FpcLoadSize
The load size. Can have a value of fpcLoadSize_Small, fpcLoadSize_Medium, or fpcLoadSize_Large from the FpcLoadSize enumerated type.

The property is read-write.

Applies To

FPCWebProxy


FPCWebProxy.OutgoingWebRequests Property

Returns a reference to an FPCWebRequestConfiguration object. The FPCWebRequestConfiguration object provides access to the properties of forward proxy and reverse proxy.

Syntax

[ oFPCProxyListenConfig = ] FPCWebProxy.OutgoingWebRequests

Possible Values

oFPCProxyListenConfig
Returns a reference to the FPCWebRequestConfiguration object.

The property is read-only.

Applies To

FPCWebProxy


FPCWebProxy.Refresh Method

Reads the object's configuration information from the Web proxy service by using a remote procedure call (RPC), discarding any changes to the current configuration that were not saved.

Syntax

FPCWebProxy.Refresh()

Applies To

FPCWebProxy


FPCWebProxy.Save Method

Saves the object's configuration information to persistent storage.

Syntax

FPCWebProxy.Save()

Applies To

FPCWebProxy


FPCWebProxy.TunnelPortRanges Property

Retrieves a reference to an FPCProxyTunnelPortRanges collection.

Syntax

[ collFPCProxyTunnelPortRanges = ] FPCWebProxy.TunnelPortRanges

Possible Values

collFPCProxyTunnelPortRanges
Reference to an FPCProxyTunnelPortRanges collection.

The property is read-only.

Applies To

FPCWebProxy


FPCWebProxy.UpstreamResolveSystem Property

Sets or retrieves which information the downstream server will use. An upstream ISA server will return both Domain Name System (DNS) or Windows Internet Name Service (WINS) name system information to a downstream server.

Syntax

FPCWebProxy.UpstreamResolveSystem [= FpcNameSystem ]

Possible Values

FpcNameSystem
The name system. It can have a value of fpc_NameSystem_DNS or fpc_NameSystem_WINS from the FpcNameSystem enumerated type.

The property is read-write.

Applies To

FPCWebProxy


FPCWebPublishingRule Object

The FPCWebPublishingRule object represents an ISA behavior known as a Web publishing rule. A Web publishing rule defines the response to attempts by outside users to access an internal site. Possible responses include:

  • Denying the request.
  • Delegating the request to a different internal server.

This object is a member of the FPCWebPublishingRules collection.

Note to C++ Programmers

This object implements the IFPCWebPublishingRule interface.

Methods

The following table lists the methods of the FPCWebPublishingRule object.

Method | Description
Refresh | Reads all the rules from persistent storage, discarding any changes to the current rule that were not saved.
Save | Saves the rule configuration to persistent storage.
SetDestination | Sets the destinations to which the rule applies.
SetRedirectUrl | Sets the action to Redirect and sets the redirect URL and its code page.

Properties

The following table lists the properties of the FPCWebPublishingRule object.

Property | Description
Action | Sets or retrieves the action that this rule performs.
AppliesToAccounts | Retrieves the collection of accounts to which the rule applies.
AppliesToDestination | Sets or retrieves the type of destination to which the rule applies.
AppliesToMethod | Sets or retrieves the method used for deciding to which users the rule applies.
ClientAddressSetsExcluded | Retrieves the collection of client address sets to which the rule does not apply.
ClientAddressSetsUsed | Retrieves the collection of client address sets to which the rule applies.
Cpid | Retrieves the code page ID (Cpid) of a URL.
Description | Sets or retrieves the description of the rule.
DestinationSetUsed | Retrieves an FPCRef object that contains the name of the FPCRefs collection used to define the destination to which the rule applies.
Enabled | Sets or retrieves whether the rule is enabled.
FTPRedirectPort | Sets or retrieves the port to redirect a request if the w3proxy service redirects its as an FTP request.
HTTPRedirectPort | Sets or retrieves the port to redirect a request if the w3proxy service redirects it as an HTTP request.
IsDefault | Retrieves whether the rule is a pre-installed rule that cannot be deleted.
Name | Sets or retrieves the name of the publishing rule.
NonSecureProtocolRedirection | Sets or retrieves the protocol used when delegating a request that came on a nonsecure channel.
Order | Retrieves the rule's order of execution in relation to the other rules.
RedirectUrl | Sets or retrieves the URL to redirect requests to when the Action property is set to the value fpcRouteRedirect.
SecureProtocolRedirection | Sets or retrieves the protocol used when delegating a request that came on a nonsecure channel.
SSLClientCertificate | Sets or retrieves how the Web proxy handles client certificates.
SSLRedirectPort | Sets or retrieves the port to redirect requests if redirecting as an SSL request.
SSLRequireSecureChannel | Sets or retrieves whether a secure channel is required.
VendorParametersSets | Retrieves a reference to an object for storing and loading of custom data into the FPCWebPublishingRule object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebPublishingRule.Action Property

Sets or retrieves the action that this rule performs.

Syntax

FPCWebPublishingRule.Action [ = PublishRouteType ]

Possible Values

PublishRouteType
Action that this rule performs. It can have a value of the FpcPublishRoute enumerated type.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.AppliesToAccounts Property

Retrieves the collection of accounts for which the rule applies.

Syntax

[ collFPCAccounts = ] FPCWebPublishingRule.AppliesToAccounts

Possible Values

collFPCAccounts
Reference to an FPCAccounts collection.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.AppliesToDestination Property

Retrieves the type of destination to which the rule applies.

Syntax

[ DestinationSelection = ] FPCWebPublishingRule.AppliesToDestination

Possible Values

DestinationSelection
Type of destination to which the rule applies. It can have a value of the FpcDestinationSelection enumerated type.

The property is read-only. It can be set through the SetDestination method.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.AppliesToMethod Property

Sets or retrieves the method used for deciding to which users the rule applies..

Syntax

FPCWebPublishingRule.AppliesToMethod [ = AppliesToType ]

Possible Values

AppliesToType
Applicability method. It can have a value of the FpcAppliesToType enumerated type.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.ClientAddressSetsExcluded Property

Retrieves the collection of client address sets to which the publishing rule does not apply.

Syntax

[ collFPCRefs = ] FPCWebPublishingRule.ClientAddressSetsExcluded

Possible Values

collFPCRefs
Reference to the FPCRefs collection.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.ClientAddressSetsUsed Property

Retrieves the collection of client address sets to which the publishing rule applies.

Syntax

[ collFPCRefs = ] FPCWebPublishingRule.ClientAddressSetsUsed

Possible Values

collFPCRefs
Reference to the FPCRefs collection.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.Cpid Property

Retrieves the code page ID (Cpid) of the URL specified by the RedirectUrl property. The Cpid is useful if a URL string contains characters that are not ANSI standard; for example, a URL string containing Japanese characters.

This property is set by the SetRedirectUrl method.

Syntax

[ lCpid = ] FPCWebPublishingRule.Cpid

Possible Value

lCpid
Long value that specifies the Cpid of a URL.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.Description Property

Sets or retrieves the description of the Web publishing rule.

Syntax

FPCWebPublishingRule.Description [ = sDescription ]

Possible Values

sDescription
String that specifies the description of the domain array.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.DestinationSetUsed Property

Retrieves an FPCRef object used to define the destination to which the rule applies.

Syntax

[ collFPCRef = ] FPCWebPublishingRule.DestinationSetUsed

Possible Values

collFPCRef
The FPCRef object used to define the destination to which the rule applies.

The property is read-only. It can be set by using the SetDestination method.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.Enabled Property

Sets or retrieves whether the rule is enabled.

Syntax

FPCWebPublishingRule.Enabled [ = bEnabled ]

Possible Values

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Rule is enabled.
FALSE | Rule is disabled.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.FTPRedirectPort Property

Sets or retrieves the port to redirect a request if the w3proxy service redirects it as an FTP request.

Syntax

FPCWebPublishingRule.FTPRedirectPort [ = lFTPRedirectPort ]

Possible Values

lFTPRedirectPort
Long value that specifies the port.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.HTTPRedirectPort Property

Sets or retrieves the port to redirect requests if redirecting as an HTTP request.

Syntax

FPCWebPublishingRule.HTTPRedirectPort [ = lHTTPRedirectPort ]

Possible Values

lHTTPRedirectPort
Long value that specifies the port.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.IsDefault Property

Retrieves whether the rule is a pre-configured rule, which cannot be deleted.

Syntax

[ bPreInstalled = ] FPCWebPublishingRule.IsDefault

Possible Values

bPreInstalled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | Rule is pre-installed.
FALSE | Rule is not pre-installed.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.Name Property

Sets or retrieves the name of the publishing rule. Names must be unique.

Syntax

FPCWebPublishingRule.Name [ = sName ]

Possible Values

sName
String that specifies the name of the rule.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.NonSecureProtocolRedirection Property

Sets or retrieves the protocol used when delegating a request that came on a nonsecure channel.

Syntax

FPCWebPublishingRule.NonSecureProtocolRedirection [ = PublishProtocolRedirectionType ]

Possible Values

PublishProtocolRedirectionType
Protocol used when delegating a request. It can have a value from the FpcPublishProtocolRedirectionType enumerated type.

The property is read-write.

Remarks

This property applies only when the Action property is set to fpcRouteRedirect.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.Order Property

Retrieves the publishing rule's order of execution in relation to the other rules. The order can be modified by the MoveUp and MoveDown methods of the FPCWebPublishingRules collection.

Syntax

[ lOrder = ] FPCWebPublishingRule.Order

Possible Values

lOrder
Long value that specifies the order of execution.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.RedirectUrl Property

Retrieves the URL to redirect requests to when the Action property is set to fpcRouteRedirect.

Syntax

[ sURL = ] FPCWebPublishingRule.RedirectUrl

Possible Values

sURL
String that specifies the URL.

The property is read only. It can be set by using the SetRedirectUrl method.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.Refresh Method

Reads all the rules from persistent storage, discarding any changes to the current rule that were not saved.

Syntax

FPCWebPublishingRule.Refresh()

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.Save Method

Saves the rule configuration to persistent storage.

Syntax

FPCWebPublishingRule.Save()

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.SecureProtocolRedirection Property

Sets or retrieves the protocol used when delegating a request that came on a secure channel.

Syntax

FPCWebPublishingRule.SecureProtocolRedirection [ = PublishProtocolRedirectionType ]

Possible Values

PublishProtocolRedirectionType
Protocol used when delegating a request. It can have a value from the FpcPublishProtocolRedirectionType enumerated type.

The property is read-write.

Remarks

This property applies only when the Action property is set to fpcRouteRedirect.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.SetDestination Method

Sets the destinations to which the rule applies.

Syntax

FPCWebPublishingRule.SetDestination(DestType, DestinationSet, ItemScope )

Parameters

DestType
Required. Defines the type of destinations. Can have a value of the FpcDestinationSelection enumerated type.
DestinationSet
Optional. Defines a set of destinations to use. Only used if DestType equals fpcDestinationSet.
ItemScope
Value from the FpcItemScope enumeration. Only used if DestType equals fpcDestinationSet. Specifies whether the destination set is one of an array's own policy elements or is an enterprise policy element. The default value is FpcArrayScope.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.SetRedirectUrl Method

Sets the action to Redirect and sets the redirect URL and its code page.

Syntax

FPCWebPublishingRule.SetRedirectUrl(Url, Cpid)

Parameters

Url
The URL to which to redirect.
Cpid
Optional. The code page for the URL string. Only used if DestType equals fpcDestinationSet.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.SSLClientCertificate Property

Sets or retrieves the client certificate to use when authenticating by using the publishing server.

Syntax

FPCWebPublishingRule.SSLClientCertificate [ = oFPCSSLCertificate ]

Possible Values

oFPCSSLCertificate
Reference to a FPCSSLCertificate object.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.SSLRedirectPort Property

Sets or retrieves the port to redirect requests if redirecting as an SSL request.

Syntax

FPCWebPublishingRule.SSLRedirectPort [ = lSSLRedirectPort ]

Possible Values

lSSLRedirectPort
Long value that specifies the port.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.SSLRequireSecureChannel Property

Sets or retrieves whether a secure channel is required.

Syntax

FPCWebPublishingRule.SSLRequireSecureChannel [ = FpcSSLRequireSecureChannel ]

Possible Values

FpcSSLRequireSecureChannel
Value from the FpcSSLRequireSecureChannelMode enumerated type.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCWebPublishingRule object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCWebPublishingRule.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRules Collection

The FPCWebPublishingRules collection provides access to a group of FPCWebPublishingRule objects of an ISA server. The rules appear in the collection by their order of execution. The order can be modified by the MoveUp and MoveDown methods.

The FPCWebPublishingRules collection is a property of the FPCArrayPolicy object.

Note to C++ Programmers

This collection implements the IFPCWebPublishingRules interface.

Methods

The following table lists the methods of the FPCWebPublishingRules collection.

Method | Description
Add | Creates a new FPCWebPublishingRule object in the list and returns a reference to it.
Item | Retrieves the given FPCWebPublishingRule object from the collection.
MoveDown | Moves the given rule down the ladder of execution.
MoveUp | Moves the given rule up the ladder of execution.
Refresh | Reads all the rules from persistent storage, discarding any changes to the current rules that were not saved.
Remove | Removes an FPCWebPublishingRule object from the collection.
Save | Saves all the rules in the collection to persistent storage.

Properties

The following table lists the properties of the FPCWebPublishingRules collection.

Property | Description
Count | Retrieves the number of FPCWebPublishingRule objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCWebPublishingRules collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebPublishingRules.Add Method

Creates a new FPCWebPublishingRule object in the list and returns a reference to it.

Syntax

[ oFPCWebPublishingRule = ] FPCWebPublishingRules.Add( sName )

Parameters

sName
Required. String that specifies the name of the new rule.

Return Value

oFPCWebPublishingRule
Reference to the FPCWebPublishingRule object.

Applies To

FPCWebPublishingRules


FPCWebPublishingRules.Count Property

Retrieves the number of FPCWebPublishingRule objects in the collection.

Syntax

[ lCount = ] FPCWebPublishingRules.Count

Possible Values

lCount
Long value that specifies the number of FPCWebPublishingRule objects.

The property is read-only.

Applies To

FPCWebPublishingRules


FPCWebPublishingRules.Item Method

Retrieves the given FPCWebPublishingRule object from the collection.

Syntax

[ vItem = ] FPCWebPublishingRules.Item( vIndex )

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCWebPublishingRule. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCWebPublishingRules


FPCWebPublishingRules.MoveDown Method

Moves the given rule down the ladder of execution.

Syntax

FPCWebPublishingRules.MoveDown( iIndex )

Parameters

iIndex
Required. Index (current order) of the rule to move down.

Applies To

FPCWebPublishingRules

See Also

MoveUp


FPCWebPublishingRules.MoveUp Method

Moves the given rule up the ladder of execution.

Syntax

FPCWebPublishingRules.MoveUp( iIndex )

Parameters

iIndex
Required. Index (current order) of the rule to move up.

Applies To

FPCWebPublishingRules

See Also

MoveDown


FPCWebPublishingRules.Refresh Method

Reads all the rules from persistent storage, discarding any changes to the current rules that were not saved.

Syntax

FPCWebPublishingRules.Refresh()

Applies To

FPCWebPublishingRules


FPCWebPublishingRules.Remove Method

Removes an FPCWebPublishingRule object from the collection.

Syntax

FPCWebPublishingRules.Remove( vItem )

Parameters

vItem
Required. Name or one-based index of the object to remove.

Applies To

FPCWebPublishingRules


FPCWebPublishingRules.Save Method

Saves all the rules in the collection to persistent storage.

Syntax

FPCWebPublishingRules.Save()

Applies To

FPCWebPublishingRules


FPCWebPublishingRules.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCWebPublishingRules collection's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCWebPublishingRules.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCWebPublishingRules


FPCWebRequestConfiguration Object

The FPCWebRequestConfiguration object provides access to the properties of the incoming Web request /outgoing Web request.

Note to C++ Programmers

This collection implements the IFPCWebRequestConfiguration interface.

Methods

The following table lists the methods of the FPCWebRequestConfiguration object.

Method | Description
Refresh | Reads all the listen entry objects from persistent storage.
Save | Saves the data to persistent storage.

Properties

The following table lists the properties of the FPCWebRequestConfiguration object.

Property | Description
AllInterfaces | Retrieves or sets whether the Web proxy listens on all the Internet Protocols (IPs) of the computer regardless of the list of entries.
AlwaysAuthenticate | Sets or retrieves whether the Web proxy always authenticates a request.
ConnectionTimeout | Sets or retrieves the time-out of a connection.
NumberOfConnections | Sets or retrieves the number of connections.
ResolveInArray | Sets or retrieves a Boolean value that defines whether to try to get the URL from another member of the array, according to the CARP algorithm.
SSLPort | Sets or retrieves the SSL port.
TCPPort | Sets or retrieves the Transmission Control Protocol (TCP) port.
UnlimitedNumberOfConnections | Sets or retrieves whether the Web proxy has an unlimited number of connections.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCWebRequestConfiguration object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebRequestConfiguration.AllInterfaces Property

Retrieves or sets whether the Web proxy listens on all the Internet Protocols (IPs) of the computer regardless of the list of entries.

Syntax

[ bAllInterfaces  = ] FPCWebRequestConfiguration.AllInterfaces

Possible Values

bAllInterfaces
Boolean value that has either of two settings:
Setting | Meaning
TRUE | The Web proxy listens on all IP addresses of the proxy computer, regardless of the individual entries within this collection.
FALSE | The Web proxy does not listen on all interfaces.

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.AlwaysAuthenticate Property

Sets or retrieves whether the Web proxy always authenticates a request even when the policy check (through rules) does not require it. Setting this property to TRUE will ensure that the logs always contain the identity of a Web request originator.

Syntax

FPCWebRequestConfiguration.AlwaysAuthenticate [= bAlwaysAuthenticate ]

Possible Values

bAlwaysAuthenticate
Boolean value. When set to TRUE, authentication is always enforced. When FALSE, authentication is disabled.

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.ConnectionTimeout Property

Sets or retrieves the time-out of a connection.

Syntax

FPCWebRequestConfiguration.ConnectionTimeout [ = iConnectionTimeout ]

Possible Values

iConnectionTimeout
Integer that specifies a time-out.

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.NumberOfConnections Property

Sets or retrieves the number of simultaneous connections to the Internet..

Syntax

FPCWebRequestConfiguration.NumberOfConnections [ = iNumberOfConnections ]

Possible Values

iNumberOfConnections
Integer that specifies the number of connections to the Internet.

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.Refresh Method

Reads all properties from persistent storage.

Syntax

FPCWebRequestConfiguration.Refresh()

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.ResolveInArray Property

Sets or retrieves a Boolean value that defines how the object will get the requested URL.

Syntax

FPCWebRequestConfiguration.ResolveInArray [ = bResolveInArray ]

Possible Values

bResolveInArray
Boolean value.that defines whether to try to get the URL from another member of the array.

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.Save Method

Saves the data to persistent storage.

Syntax

FPCWebRequestConfiguration.Save()

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.SSLPort Property

Sets or retrieves the SSL port.

Syntax

FPCWebRequestConfiguration.SSLPort [ = iSSLPort ]

Possible Values

iSSLPort
Integer that specifies the SSL port.

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.TCPPort Property

Sets or retrieves the Transmission Control Protocol (TCP) port.

Syntax

FPCWebRequestConfiguration.TCPPort [ = iTCPPort ]

Possible Values

iTCPPort
Integer that specifies TCP port.

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.UnlimitedNumberOfConnections Property

Sets or retrieves whether the Web proxy has an unlimited number of connections.

Syntax

FPCWebRequestConfiguration.UnlimitedNumberOfConnections [ = bUnlimitedNumberOfConnections ]

Possible Values

bUnlimitedNumberOfConnections
A Boolean value that specifies whether the Web proxy has an unlimited number of connections.

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCWebRequestConfiguration object's storage.

Syntax

[ collFPCVendorParametersSets = ] FPCWebRequestConfiguration.VendorParametersSets

Possible Values

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCWebRequestConfiguration


FPCWebSession Object

The FPCWebSession object represents a single Web session of an ISA Server computer. A Web session is a period of time during which a user's browser requests information from a Web server.

This object is a member of the FPCWebSessions collection.

Note to C++ Programmers

This object implements the IFPCWebSession interface.

Methods

The following table lists the methods of the FPCWebSession object.

Method | Description
AbortSession | Aborts the session using a remote procedure call (RPC), and removes the session from the collection.
Refresh | Reads the FPCWebSession objects using an RPC call.

Properties

The following table lists the properties of the FPCWebSession object.

Property | Description
ClientMachine | Retrieves the client computer for this session.
UserName | Retrieves the user name for this session.
WebSessionAdditionalInfo | Retrieves a pointer to the FPCWebSessionAdditionalInfo object.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebSession.AbortSession Method

Stops the session.

Syntax

FPCWebSession.AbortSession()

Applies To

FPCWebSession


FPCWebSession.ClientMachine Property

Retrieves the address of the client computer.

Syntax

[ sClientMachine = ] FPCWebSession.ClientMachine

Possible Values

sClientMachine
String that specifies the client computer.

The property is read-only.

Applies To

FPCWebSession


FPCWebSession.Refresh Method

Reads all properties of the FPCWebSession object from the Web proxy service by means of a remote procedure call (RPC).

Syntax

FPCWebSession.Refresh()

Remarks

FPCWebSession is not a persistent object. There is no persistent storage for this object because its attributes are supplied at run time by ISA. An RPC call is used to query ISA services about its sessions because the information is dynamic.

Applies To

FPCWebSession


FPCWebSession.UserName Property

Retrieves the client Windows NT/Windows 2000 account.

Syntax

[ sName = ] FPCWebSession.UserName

Possible Values

sName
String that specifies the Windows NT/Windows 2000 account of the client.

The property is read-only.

Applies To

FPCWebSession


FPCWebSession.WebSessionAdditionalInfo Property

Returns a reference to the FPCWebSessionAdditionalInfo object, which contains additional properties of the Web session.

Syntax

[ oFPCWebSessionAdditionalInfo = ] FPCWebSession.WebSessionAdditionalInfo

Possible Values

oFPCWebSessionAdditionalInfo
Reference to the FPCWebSessionAdditionalInfo object.

The property is read-only.


FPCWebSessions Collection

The FPCWebSessions collection provides access to a group of FPCWebSession objects. Each FPCWebSession object represents one Web session of an ISA Server computer. A Web session is a period of time during which a user's browser requests information from a Web server. This collection is a property of the FPCServer object.

Note to C++ Programmers

This collection implements the IFPCWebSessions interface.

Methods

The following table lists the methods of the FPCWebSessions collection.

Method | Description
Item | Retrieves the given object from the collection.
Refresh | Reads all the objects using a remote procedure call (RPC).

Properties

The following table lists the properties of the FPCWebSessions collection.

Property | Description
Count | Retrieves the number of FPCWebSession objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebSessions.Count Property

Retrieves the number of FPCWebSession objects in the collection.

Syntax

[ iCount = ] FPCWebSessions.Count

Possible Values

iCount
Integer that specifies the number of FPCWebSession objects.

The property is read-only.

Applies To

FPCWebSessions


FPCWebSessions.Item Method

Retrieves the given FPCWebSession object from the collection.

Syntax

[ vItem = ] FPCWebSessions.Item( vUserOrIndex, ClientMachine )

Parameters

vUserOrIndex
Required. User name or one-based index of the object to retrieve.
ClientMachine
Optional. Client machine.

Return Value

vItem
If successful, returns a reference to an object of type FPCWebSession. Otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted using an error handler.

Applies To

FPCWebSessions


FPCWebSessions.Refresh Method

Retrieves all the FPCWebSession objects from the Web proxy service using a remote procedure call (RPC).

Syntax

FPCWebSessions.Refresh()

Remarks

FPCWebSession is not a persistent object. There is no persistent storage for this object because its attributes are supplied at run time by ISA. An RPC call is used to query ISA services about its sessions because the information is dynamic.

Applies To

FPCWebSessions


FPCWebSessionAdditionalInfo Object

The FPCWebSessionAdditionalInfo object represents additional information about an FPCWebSession object. This object is a property of an FPCWebSession object.

Note to C++ Programmers

This collection implements the IFPCWebSessionAdditionalInfo interface.

Properties

The following table lists the properties of the FPCWebSessionAdditionalInfo object.

Property | Description
ConnectionsNumber | Retrieves the number of requests for this session.
Duration | Retrieves the duration of the session.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebSessionAdditionalInfo.ConnectionsNumber Property

Retrieves the number of requests for a session.

Syntax

[ iConnectionsNumber = ] FPCWebSessionAdditionalInfo.ConnectionsNumber

Possible Values

iConnectionsNumber
Integer that specifies the number of requests.

The property is read-only.

Applies To

FPCWebSessionAdditionalInfo


FPCWebSessionAdditionalInfo.Duration Property

Retrieves the duration of the session.

Syntax

[ iDuration = ] FPCWebSessionAdditionalInfo.Duration

Possible Values

iDuration
Integer that specifies the session duration.

The property is read-only.

Applies To

FPCWebSessionAdditionalInfo


Enumerated Types

This section describes the enumerated data values used by the Internet Security and Acceleration Server (ISA) administration COM objects. They are defined in comenum.h.

  • FpcAccounttypes
  • FpcActionTypes
  • FpcActiveCachingPolicy
  • FpcAlertsAccessRights
  • FpcAlertTypes
  • FpcAppliesToContentMethod
  • FpcAppliesToType
  • FpcArrayType
  • FpcAuthType
  • FpcClientBackupRouteType
  • FpcBackupRouteType
  • FpcBackupType
  • FpcBrowserConfigScriptFlag
  • FpcCacheExpirationPolicy
  • FpcComponents
  • FpcConnectionDirectionType
  • FpcConnectionProtocolType
  • FpcDestinationAddressType
  • FpcDestinationSelection
  • FpcFetchUrlFlags
  • FpcFilterDirection
  • FpcFilterPriority
  • FpcFwAccessByType
  • FpcFwForwardType
  • FpcGetIpsFlags
  • FpcIncludeStatus
  • FpcItemScope
  • FpcLoadSize
  • FpcLogFileDirectoryType
  • FpcLogFormat
  • FpcLoggingComponents
  • FpcLogPeriod
  • FpcLogType
  • FpcNameSystem
  • FpcOperationModes
  • FpcPfDirectionType
  • FpcPfFilterMode
  • FpcPfFilterStatusType
  • FpcPfFilterType
  • FpcPfIcmpCodeOptions
  • FpcPfIcmpTypeOptions
  • FpcPfLocalHostType
  • FpcPfLocalPortType
  • FpcPfProtocolType
  • FpcPfRemoteHostType
  • FpcPfRemotePortType
  • FpcPolicyUsed
  • FpcPrimaryRouteType
  • FpcProtocolRuleAction
  • FpcProtocolSelectionType
  • FpcPublishProtocolRedirectionType
  • FpcPublishRoute
  • FpcPublishRouteType
  • FpcRouteCacheAction
  • FpcRouteType
  • FpcRuleActions
  • FpcScheduleDays
  • FpcScheduledContentDownloadPeriod
  • FpcScheduleHours
  • FpcSecurityScope
  • FpcServices
  • FpcSessionsAccessRights
  • FpcSSLClientCertificateMode
  • FpcSSLRequireSecureChannelMode
  • FpcTimeScale


FpcAccountTypes

The FpcAccountTypes enumerated type contains values that describe. types of Windows NT/Windows 2000 accounts.

enum FpcAccountTypes {
  fpcAccountTypeUser,
  fpcAccountTypeGroup,
  fpcAccountTypeDomain,
  fpcAccountTypeAlias,
  fpcAccountTypeWellKnownGroup
};

Members

fpcAccountTypeUser (0)
A user.
fpcAccountTypeGroup (1)
A group of users
fpcAccountTypeDomain (2)
A domain of users.
fpcAccountTypeAlias (3)
An alias.
fpcAccountTypeWellKnownGroup (4)
A predefined account such as "Everyone".

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcActionTypes

The FpcActionTypes enumerated type contains values that describe types of action that events can trigger.

enum FpcActionTypes {
  fpcAlertActionLogEvent,
  fpcAlertActionCommand,
  fpcAlertActionSendMail,
  fpcAlertActionStopServices,
  fpcAlertActionStartServices
};

Members

fpcAlertActionLogEvent
Logs event to the system event log.
fpcAlertActionCommand
Runs a specified command.
fpcAlertActionSendMail
Sends Mail message.
fpcAlertActionStopServices
Stops ISA services.
fpcAlertActionStartServices
Starts ISA services.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcActiveCachingPolicy

The FpcActiveCachingPolicy enumerated type contains values that describe the behavior of the active caching mechanism.

enum FpcActiveCachingPolicy {
  fpcActiveCachingEmphasizeOnFewerNetworkAccesses,
  fpcActiveCachingNoEmphasize,
  fpcActiveCachingEmphasizeOnFasterUserResponse
};

Members

fpcActiveCachingEmphasizeOnFewerNetworkAccesses
Less active caching is initiated.
fpcActiveCachingNoEmphasize
Average caching behavior is used.
fpcActiveCachingEmphasizeOnFasterUserResponse
More active caching is initiated.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcAlertsAccessRights

Information not available for this release.

FpcAlertsAccessRights {
  fpcAlertsRight_Delete                 = 0x10000,
  fpcAlertsRight_Read_Control           = 0x20000,
  fpcAlertsRight_Write_Dac              = 0x40000,
  fpcAlertsRight_Write_Owner            = 0x80000,
  fpcAlertsRight_Synchronize            = 0x100000,
  fpcAlertsRight_Access_System_Security = 0x1000000,
  fpcAlertsRight_Generic_Read           = 0x80000000,
  fpcAlertsRight_Generic_Write          = 0x40000000,
  fpcAlertsRight_Generic_Execute        = 0x20000000,
  fpcAlertsRight_Generic_All            = 0x10000000,
  fpcAlertsRight_Read                   = 0x00000001,
  fpcAlertsRight_Reset                  = 0x00000002
};

Members

fpcAlertsRight_Delete
TBD
fpcAlertsRight_Read_Control
TBD
fpcAlertsRight_Write_Dac
TBD
fpcAlertsRight_Write_Owner
TBD
fpcAlertsRight_Synchronize
TBD
fpcAlertsRight_Access_System_Security
TBD
fpcAlertsRight_Generic_Read
TBD
fpcAlertsRight_Generic_Write
TBD
fpcAlertsRight_Generic_Execute
TBD
fpcAlertsRight_Generic_All
TBD
fpcAlertsRight_Read
TBD
fpcAlertsRight_Reset
TBD

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcAlertTypes

The FpcAlertTypes enumerated type contains values that describe alert types.

enum FpcAlertTypes {
  fpcAlertTypePacketRate,
  fpcAlertTypeProtocolViolation,
  fpcAlertTypeDiskFull,
  fpcNumAlertTypes
};

Members

fpcAlertTypePacketRate
TBD
fpcAlertTypeProtocolViolation
TBD
fpcAlertTypeDiskFull
TBD
fpcNumAlertTypes
TBD

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcAppliesToContentMethod

The FpcAppliesToContentMethod enumerated type contains values that identify the type of content used in a rule.

enum FpcAppliesToContentMethod {
  fpcAppliesToAllContent,
  fpcAppliesToSpecifiedContent
};

Members

fpcAppliesToAllContent
Rule applies to all types of content.
fpcAppliesToSpecifiedContent
Rule applies to specified content.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcAppliesToType

The FpcAppliesToType enumerated type contains values that describe types of request origins to which a rule applies.

enum FpcAppliesToType {
  fpcAppliesToAll,
  fpcAppliesToUsers,
  fpcAppliesToClientSets
};

Members

fpcAppliesToAll
Applies to all requests regardless of origin.
fpcAppliesToUsers
Applies to requests from specified users.
fpcAppliesToClientSets
Applies to requests from specified computers.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcArrayType

The FpcArrayType enumerated type contains values that identify whether an array is an independent array or a domain array.

enum FpcArrayType {
  fpcArrayStandAlone,
  fpcArrayShared
};

Members

fpcArrayStandAlone
Array is an independent (registry-based) array with single server.
fpcArrayShared
Array is a shareable (DS base) domain array with an unlimited number of servers.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcAuthType

The FpcAuthType enumerated type contains values that describeauthentication methods used for inter server connections.

enum FpcAuthType {
  fpcUiAuthBasic,
  fpcUiAuthNtlm,
  fpcUiAuthDigest
};

Members

fpcUiAuthBasic (0)
Basic authentication.
fpcUiAuthNtlm (1)
Windows NT Challenge/Response authentication.
fpcUiAuthDigest (2)
Digest authentication.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcClientBackupRouteType

Information not available for this release.

enum FpcClientBackupRouteType {
  fpcClientBackupRouteDirectToInternet,
  fpcClientBackupRouteViaProxy
};

Members

fpcClientBackupRouteDirectToInternet
TBD
fpcClientBackupRouteViaProxy
TBD

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcBackupRouteType

The FpcBackupRouteType enumerated type contains values that determine the backup route type.

enum FpcBackupRouteType {
  fpcBackupRouteNone,
  fpcBackupRouteDirect,
  fpcBackupRouteUpstream
};

Members

fpcBackupRouteNone
There is no backup route.
fpcBackupRouteDirect
Backup route is direct to the Internet.
fpcBackupRouteUpstream
Backup route is through an upstream proxy server.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcBackupType

Information not available for this release.

enum FpcBackupType {
  fpcBackupArrayConfiguration,
  fpcBackupEnterpriseConfiguration
}

Members

fpcBackupArrayConfiguration
TBD
fpcBackupEnterpriseConfiguration
TBD

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcBrowserConfigScriptFlag

The FpcBrowserConfigScriptFlag enumerated type provides flags that determine the type of browser configuration script.

enum FPCBrowserConfigScriptFlag {
  fpcBrowserDefaultScript,
  fpcBrowserCustomScript
};

Members

fpcBrowserDefaultScript
Use the default script.
fpcBrowserCustomScript
Use the custom script.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcCacheExpirationPolicy

The FpcCacheExpirationPolicy enumerated type contains values that define how soon cached Web pages expire.

enum FpcCacheExpirationPolicy {
  fpcCachePolicyCustom,
  fpcCachePolicyEmphasizeMoreUpdates,
  fpcCachePolicyNoEmphasize,
  fpcCachePolicyEmphasizeMoreCacheHits
};

Members

fpcCachePolicyCustom
Custom policy.
fpcCachePolicyEmphasizeMoreUpdates
Cached object expires more quickly.
fpcCachePolicyNoEmphasize
Average behavior.
fpcCachePolicyEmphasizeMoreCacheHits
Cached objects live longer.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcComponents

Information not available for this release.

enum FpcComponents {
  fpcNoComponents       =0,
  fpcPacketFiltering    =1,
  fpcNAT                =2,
  fpcWebProxy           =4,
  fpcHTTPTransparent    =8,
  fpcGenericFwProtocols =16,
  fpcFirewallExtensions =32,
  fpcAllComponents      =255
};

Members

fpcNoComponents (0)
TBD
fpcPacketFiltering (1)
TBD
fpcNAT (2)
TBD
fpcWebProxy (4)
TBD
fpcHTTPTransparent (8)
TBD
fpcGenericFwProtocols (16)
TBD
fpcFirewallExtensions (32)
TBD
fpcAllComponents (255)
TBD

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcConnectionDirectionType

The FpcConnectionDirectionType enumerated type contains values that describe the type of Firewall service connection.

enum FpcConnectionDirectionType {
  fpcInbound,
  fpcOutbound
};

Members

fpcInbound
Inbound connection.
fpcOutbound
Outbound connection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcConnectionProtocolType

The FpcConnectionProtocolType enumerated type contains values that describe the connection protocol.

enum FpcConnectionProtocolType {
  fpcTCP,
  fpcUDP
};

Members

fpcTCP
Transmission Control Protocol (TCP) IP.
fpcUDP
User Datagram Protocol (UDP) IP.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcDestinationAddressType

The FpcDestinationAddressType enumerated type contains values that describe the type of destination.

enum FpcDestinationAddressType {
  fpcDestinationTypeDomain,
  fpcDestinationTypeSingleIp,
  fpcDestinationTypeIpRange
};

Members

fpcDestinationTypeDomain
Destination defined by domain name.
fpcDestinationTypeSingleIp
Destination defined by single Internet Protocol (IP).
fpcDestinationTypeIpRange
Destination defined by an IP range.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcDestinationSelection

The FpcDestinationSelection enumerated type contains values that describe the type of destinations referred to in a rule.

enum FpcDestinationSelection {
  fpcAllDestinations,
  fpcAllInternalDestinations,
  fpcAllExternalDestinations,
  fpcDestinationSet,
  fpcAllExceptDestinationSet
};

Members

fpcAllDestinations
All destinations.
fpcAllInternalDestinations
All internal destinations.
fpcAllExternalDestinations
All external destinations.
fpcDestinationSet
Destinations that are part of a specified set.
fpcAllExceptDestinationSet
All destinations except those in the specified destination set.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcFetchUrlFlags

The FpcFetchUrlFlags enumerated type contains flags that control FetchUrl method behavior.

enum FpcFetchUrlFlags {
  fpcFetchTtlIfNone,
  fpcFetchTtlOverride,
  fpcFetchSynchronous,
  fpcFetchNoArrayRouting,
  fpcFetchForceCache
};

Members

fpcFetchTtlIfNone
The TtlInMinutes parameter should be used only if the object does not contain an "Expires" or "Cache-Control: max-age" HTTP header.
fpcFetchTtlOverride
The TtlInMinutes parameter takes precedence over any HTTP headers in the object.
fpcFetchSynchronous
Method will not return until the fetch is completed.
fpcFetchNoArrayRouting
Fetches on a target server even if another array member is the preferred location.
fpcFetchForceCache
Caches even if object cannot normally be cached.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcFilterDirection

The FpcFilterDirection enumerated type contains values that describe whether a filter operates in forward reverse, or both modes.

enum FpcFilterDirection {
  fpcFilterDirectionForward,
  fpcFilterDirectionReverse,
  fpcFilterDirectionBoth
};

Members

fpcFilterDirectionForward
Filter applies to incoming packets.
fpcFilterDirectionReverse
Filter applies to outgoing packets.
fpcFilterDirectionBoth
Filter applies to incoming and outgoing packets.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcFilterPriority

The FpcFilterPriority enumerated type defines the filter priority.

enum FpcFilterPriority {
  fpcFilterPriority_Low,
  fpcFilterPriority_Medium,
  fpcFilterPriority_High
};

Members

fpcFilterPriority_Low
Filter has low priority.
fpcFilterPriority_Medium
Filter has medium priority.
fpcFilterPriority_High
Filter has high priority.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcFwAccessByType

The FpcFwAccessByType enumerated type contains values that describe the communication level that any Firewall client uses to contact the Firewall service.

enum FpcFwAccessByType {
  fpcClientAccessSetByIp,
  fpcClientAccessSetByName
};

Members

fpcClientAccessSetByIp
Identifies by Internet Protocol (IP).
fpcClientAccessSetByName
Identifies by name.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcFwForwardType

The FpcFwForwardType enumerated type specifies the mode of proxy forwarding.

typedef enum FpcFwForwardType {
  fpcPrimaryConnection,
  fpcChaining
};

Members

fpcPrimaryConnection
Forward requests to primary connection.
fpcChaining
Forward requests to another chaining proxy server.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcGetIpsFlags

The FpcGetIpsFlags enumerated type contains values that specify internal or external Internet Protocol (IP) addresses.

enum FpcGetIpsFlags {
  fpcInternalOnly,
  fpcExternalOnly,
  fpcInternalAndExternal
};

Members

fpcInternalOnly
Internal IPs only.
fpcExternalOnly
External IPs only.
fpcInternalAndExternal
Both internal and external.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcIncludeStatus

The FpcIncludeStatus enumerated type defines whether an account is included in or excluded from the list of accounts to which a rule applies.

enum FpcIncludeStatus {
  fpcInclude,
  fpcExclude
};

Members

fpcInclude
Account is included.
fpcExclude
Account is excluded.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcItemScope

The FpcItemScope enumerated type specifies the scope of the item. FpcItemScope designates whether the item has array-level scope or enterprise-level scope. This enumerated type is used for policy elements such as protocols, destination sets, schedules, and so forth.

enum FpcItemScope {
  fpcArrayScope,
  fpcEnterpriseScope
};

Members

fpcArrayScope
Item has array-level scope.
fpcEnterpriseScope
Item has enterprise-level scope.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcLoadSize

The FpcLoadSize enumerated type contains values that describe the Web proxy load size.

enum FpcLoadSize {
  fpcLoadSize_Small,
  fpcLoadSize_Medium,
  fpcLoadSize_Large
};

Members

fpcLoadSize_Small
Small load size.
fpcLoadSize_Medium
Medium load size.
fpcLoadSize_Large
Large load size.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcLogFileDirectoryType

The FpcLogFileDirectoryType enumerated type contains values that describe the path type for the log file.

enum FpcLogFileDirectoryType {
  fpcFullPath,
  fpcRelativePath
};

Members

fpcFullPath
The directory of the log files is given in full path.
fpcRelativePath
The directory of the log files is relative to the ISA Install directory.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcLogFormat

The FpcLogFormat enumerated type contains values that describe whether the log will be in verbose or regular format.

enum FpcLogFormat {
  fpcLogFormatVerbose,
  fpcLogFormatRegular
};

Members

fpcLogFormatVerbose
Verbose log format.
fpcLogFormatRegular
Regular log format.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcLoggingComponents

The FpcLoggingComponents enumerated type contains values that describe the type of logging component.

enum FpcLoggingComponents {
  fpcProxyWebLog,
  fpcProxyFwLog,
  fpcProxyPacketFiltersLog
};

Members

fpcProxyWebLog
The Web proxy log.
fpcProxyFwLog
The Firewall service log.
fpcProxyPacketFiltersLog
Packet filters log.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcLogPeriod

The FpcLogPeriod enumerated type contains values that describe the period of time before starting anew text log file.

enum FpcLogPeriod {
  FpcLogDaily =1,
  FpcLogWeekly,
  FpcLogMonthly,
  FpcLogYearly
};

these options identify logging periods for text files

Members

FpcLogDaily
One file per day
FpcLogWeekly
One log file per week
FpcLogMonthly
One log file per month
FpcLogYearly
One log file per year.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcLogType

The FpcLogType enumerated type contains values that describe the logging method.

enum FpcLogType {
  fpcFile_EXT_Format,
  fpcFile_IIS_Format,
  fpcODBC
};

Members

fpcFile_EXT_Format
Logging the World Wide Web Consortium (W3C) extended format to text log files.
fpcODBC
Logging to the open database connectivity (ODBC) log.
fpcFile_IIS_Format
Logging the Internet Information Services (IIS) format to text log files.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcNameSystem

The FpcNameSystem enumerated type contains values that describe the name system used for CARP hashing.

enum FpcNameSystem {
  fpcNameSystem_DNS,
  fpcNameSystem_WINS
};

Members

fpcNameSystem_DNS
Use the Domain Name System (DNS).
fpcNameSystem_WINS
Use the Windows Internet Name Service (WINS) name system.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcOperationModes

The FpcOperationModes enumerated type contains values that describe alerting operation modes.

enum FpcOperationModes {
  fpcCountThreshold,
  fpcRateThreshold,
  fpcIntervalThreshold
};

Members

fpcCountThreshold
Events count before re-raising alert.
fpcRateThreshold
Minimal rate of events per second for raising alert.
fpcIntervalThreshold
Minimal interval in minutes before re-raising alert.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfDirectionType

The FpcPfDirectionType enumerated type contains values that describe packet directions.

enum FpcPfDirectionType {
  fpcPfDirectionIndexIn,
  fpcPfDirectionIndexOut,
  fpcPfDirectionIndexBoth
};

Members

fpcPfDirectionIndexIn (1)
In direction
fpcPfDirectionIndexOut (2)
Out direction
fpcPfDirectionIndexBoth (3)
Both directions (in and out)

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfFilterMode

The FpcPfFilterMode enumerated type contains values that describe the type of packet filter, either allowing or blocking

enum FpcPfFilterMode {
  fpcAllowingPacketFilter,
  fpcBlockingPacketFilter
};

Members

fpcAllowingPacketFilter (1)
A regular packet filter that allows the packets to pass.
fpcBlockingPacketFilter (2)
A blocking filter that drops packets that match the filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfFilterStatusType

The FpcPfFilterStatusType enumerated contains values that describe packet-filter status.

enum FpxPfFilterStatusType {
  fpcFilterNotChanged,
  fpcFilterWasAdded,
  fpcFilterWasRemoved,
  fpcFilterWasChanged
};

Members

fpcFilterNotChanged (1)
No changes occurred in the filter.
fpcFilterWasAdded
A packet filter was added.
fpcFilterWasRemoved
A packet filter was removed.
fpcFilterWasChanged
A packet filter was changed.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfFilterType

The FpcPfFilterType enumerated type contains values that describe packet filter types.

enum FpcPfFilterType {
  fpcCustomFilterType,
  fpcDnsLookupPredefinedType,
  fpcIcmpAllOutboundPredefinedType,
  fpcIcmpPingResponsePredefinedType,
  fpcIcmpPingQueryPredefinedType,
  fpcIcmpSrcQuenchPredefinedType,
  fpcIcmpTimeoutPredefinedType,
  fpcIcmpUnreachablePredefinedType,
  fpcPptpCallPredefinedType,
  fpcPptpReceivePredefinedType,
  fpcSmtpPredefinedType,
  fpcPop3PredefinedType,
  fpcIdentdPredefinedType,
  fpcHttpServerPredefinedType,
  fpcHttpsServerPredefinedType,
  fpcNetbiosWinsClientPredefinedType,
  fpcNetbiosAllPredefinedType
};

Members

fpcCustomFilterType (1)
A custom filter with options set by the user. Custom filter options can also be seen through the administration tool.
fpcDnsLookupPredefinedType (2)
Describes the Domain Name System (DNS) lookup predefined static filter.
fpcIcmpAllOutboundPredefinedType (3)
Describes the Internet Control Message Protocol (ICMP) outbound predefined static filter.
fpcIcmpPingResponsePredefinedType (4)
Describes the ICMP ping response predefined static filter.
fpcIcmpPingQueryPredefinedType (5)
Describes the ICMP ping query predefined static filter.
fpcIcmpSrcQuenchPredefinedType (6)
Describes the ICMP source quench predefined static filter.
fpcIcmpTimeoutPredefinedType (7)
Describes the ICMP timeout predefined static filter.
fpcIcmpUnreachablePredefinedType (8)
Describes the ICMP unreachable predefined static filter.
fpcPptpCallPredefinedType (9)
Describes the PPTP call predefined static filter.
fpcPptpReceivePredefinedType (10)
Describes the PPTP receive predefined static filter.
fpcSmtpPredefinedType (11)
Describes the SMTP receive predefined static filter.
fpcPop3PredefinedType (12)
Describes the POP3 predefined static filter.
fpcIdentdPredefinedType (13)
Describes the Identified predefined static filter.
fpcHttpServerPredefinedType (14)
Describes the HTTP server predefined static filter.
fpcHttpsServerPredefinedType (15)
Describes the HTTPS server predefined static filter.
fpcNetbiosWinsClientPredefinedType (16)
Describes the Netbios WINS predefined static filter.
fpcNetbiosAllPredefinedType (17)
Describes the Netbios all predefined static filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfIcmpCodeOptions

The FpcPfIcmpCodeOptions enumerated type represents Internet Control Message Protocol (ICMP) code options used by the IP packet filter.

enum FpcPfIcmpCodeOptions {
  fpcPfAnyIcmpCode,
  fpcPfFixedIcmpCode
};

Members

fpcPfAnyIcmpCode (1)
Any ICMP code.
fpcPfFixedIcmpCode
Fixed ICMP code.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfIcmpTypeOptions

The FpcPfIcmpTypeOptions enumerated type represents Internet Control Message Protocol (ICMP) type options used by the IP packet filter.

enum FpcPfIcmpTypeOptions {
  fpcPfAnyIcmpType,
  fpcPfFixedIcmpType
};

Members

fpcPfAnyIcmpType (1)
Any ICMP type.
fpcPfFixedIcmpType
Fixed ICMP type.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfLocalHostType

The FpcPfLocalHostType enumerated type contains values that describe the type of local host used by the packet filter.

enum FpcPfLocalHostType {
  fpcPfDefaultProxyExternalIp,
  fpcPfSpecificProxyIp,
  fpcPfInternalComputer,
  fpcPfInternalIPRange
};

Members

fpcPfDefaultProxyExternalIp (1)
No host specified (default external IP).
fpcPfSpecificProxyIp (2)
Proxy IP specified.
fpcPfInternalComputer (3)
Internal computer specified.
fpcPfInternalIPRange (4)
A range of internal IPs.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfLocalPortType

The FpcPfLocalPortType enumerated type represents the port options used by the packet filter.

enum FpcPfLocalPortType {
  fpcPfAnyPort,
  fpcPfFixedPort,
  fpcPfDynamicPort
};

Members

fpcPfAnyPort (1)
Any port.
fpcPfFixedPort (2)
Fixed port (followed by port number).
fpcPfDynamicPort (3)
Dynamic port (1024-5000).

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfProtocolType

The FpcPfProtocolType enumerated type contains values that describe predefined static packet filters Internet Protocol (IP) ports.

enum FpcPfProtocolType {
  fpcPfAnyProtocolIpIndex,
  fpcPfIcmpProtocolIpIndex,
  fpcPfTcpProtocolIpIndex,
  fpcPfUdpProtocolIpIndex
};

Members

fpcPfAnyProtocolIpIndex (0)
Any protocol.
fpcPfIcmpProtocolIpIndex (1)
Internet Control Message Protocol (ICMP) protocol.
fpcPfTcpProtocolIpIndex (6)
Translation Control Protocol (TCP) protocol.
fpcPfUdpProtocolIpIndex (17)
User Datagram Protocol (UDP) protocol.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfRemoteHostType

The FpcPfRemoteHostType enumerated type contains values that describe the remote host type used by the packet filter.

enum FpcPfRemoteHostType {
  fpcPfAnyHost,
  fpcPfSingleHost,
  fpcPfExternalIpRange
};

Members

fpcPfAnyHost (1)
Any host possible
fpcPfSingleHost
Single host specified
fpcPfExternalIpRange
A range of external IPs.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfRemotePortType

The FpcPFRemotePortType enumerated type contains values that describe packet filter port-type options.

enum FpcPfRemotePortType {
  fpcPfAnyRemotePort,
  fpcPfFixedRemotePort
};

Members

fpcPfAnyRemotePort (1)
Any port.
fpcPfFixedRemotePort
Fixed port (followed by port number).

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPolicyUsed

The FpcPolicyUsed enumerated type specifies whether the array uses local and/or enterprise policy.

enum FpcPolicyUsed {
  fpcArrayPolicy,
  fpcEnterprisePolicy,
  fpcArrayAndEnterprisePolicies
};

Members

fpcArrayPolicy
Uses array policy only.
fpcEnterprisePolicy
Uses enterprise policy only.
fpcArrayAndEnterprisePolicies
Uses local and enterprise policies.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPrimaryRouteType

The FpcPrimaryRouteType enumerated type provides values that determine the primary route type.

enum FpcPrimaryRouteType {
  fpcPrimaryRouteDirect,
  fpcPrimaryRouteUpstream,
  fpcPrimaryRouteAlternate
};

Members

fpcPrimaryRouteDirect
Sends request directly to Internet.
fpcPrimaryRouteUpstream
Sends request to an upstream ISA server or array.
fpcPrimaryRouteAlternate
Routes the request to any other server.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcProtocolRuleAction

The FpcProtocolRuleAction enumerated type contains values that describethe types of actions performed by the protocol rules.

enum FpcProtocolRuleAction {
  fpcActionAllow,
  fpcActionDeny
};

Members

fpcActionAllow
Allows Internet Protocol (IP) connection requests.
fpcActionDeny
Denies IP connection requests.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcProtocolSelectionType

The FpcProtocolSelectionType enumerated type contains values that describe type of protocols to which a protocol rule applies.

enum FpcProtocolSelectionType {
  fpcAllIpTraffic,
  fpcSpecifiedProtocols,
  fpcAllExceptSpecifiedProtocols
};

Members

fpcAllIpTraffic
All Internet Protocol (IP) connections.
fpcSpecifiedProtocols
Protocols specified by the SpecifiedProtocols property.
fpcAllExceptSpecifiedProtocols
All protocols except specified protocols.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPublishProtocolRedirectionType

The FpcPublishProtocolRedirectionType enumerated type contains values that describe the protocol chosen when redirecting a Web request.

enum FpcPublishProtocolRedirectionType {
  fpcHTTP,
  fpcFTP,
  fpcSSL
};

Members

fpcHTTP
The request is routed using the HTTP protocol.
fpcFTP
The request is routed using the FTP protocol.
fpcSSL
The request is routed using the SSL protocol.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPublishRoute

The FpcPublishRoute enumerated type contains values that describe opions for Web publishing rules.

enum FpcPublishRoute {
  fpcRouteDiscard,
  fpcRouteRedirect
};

Members

fpcRouteDiscard
TBD
fpcRouteRedirect
TBD

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPublishRouteType

The FpcPublishRouteType enumerated type contains values that describethe type of action performed by a publishing rule.

enum FpcPublishRouteType {
  fpcRouteDiscard,
  fpcRouteRedirect
};

Members

fpcRouteDiscard
Denies the desired access.
fpcRouteRedirect
Redirects the request to another computer.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcRouteCacheAction

The FpcRouteCacheAction enumerated type contains values that describe situations in which the proxy utilizes the cache rather than performing the routing action specified in a routing rule.

enum FpcRouteCacheAction {
  fpcServeFromCacheIfValidObjectExists,
  fpcServeFromCacheIfObjectExists,
  fpcServeFromCacheOnly
};

Members

fpcServeFromCacheIfValidObjectExists
Uses valid cached objects; otherwise, connects to the Internet to get a new version of it.
fpcServeFromCacheIfObjectExists
Uses object from cache (regardless of validity). If it does not exist, connects to the Internet.
fpcServeFromCacheOnly
Uses object from cache (regardless of validity). If it doesn't exist, it returns an error page, but does not connect to the Internet.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcRouteType

Information not available for this release.

typedef enum FpcRouteType {
  fpcRouteNone            = -1,
  fpcRouteDirect          =  0,
  fpcRouteServer          =  1,
  fpcRouteCluster         =  2,
  fpcRouteAutoDetect      =  3,
  fpcRouteSimpleServer    =  4
};

Members

fpcRouteNone (-1)
TBD
fpcRouteDirect (0)
TBD
fpcRouteServer (1)
TBD
fpcRouteCluster (2)
TBD
fpcRouteAutoDetect (3)
TBD
fpcRouteSimpleServer (4)
TBD

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcRuleActions

The FpcRuleActions enumerated type contains values that describe actions performed when a rule criterion is met.

enum FpcRuleActions {
  fpcRuleActionPermit,
  fpcRuleActionDeny,
  fpcRuleActionRedirect
};

Members

fpcRuleActionPermit
Permits access to the requested Web page.
fpcRuleActionDeny
Denies access to the requested Web page.
fpcRuleActionRedirect
Redirects to a specific Web page.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcScheduleDays

The FpcScheduleDays enumerated type contains values that describe the days of the week. Used in schedule templates.

enum FpcScheduleDays {
  fpcALL_WEEK,
  fpcSUN,
  fpcMON,
  fpcTUE,
  fpcWED,
  fpcTHU,
  fpcFRI,
  fpcSAT
};

Members

fpcALL_WEEK
All days in week.
fpcSUN
Sunday.
fpcMON
Monday.
fpcTUE
Tuesday.
fpcWED
Wednesday.
fpcTHU
Thursday.
fpcFRI
Friday.
fpcSAT
Saturday.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcScheduledContentDownloadPeriod

The FpcScheduledContentDownloadPeriod enumerated type contains values that describe prefetching periods.

enum FpcScheduledContentDownloadPeriod {
  fpcDownloadOnce,
  fpcDownloadDaily,
  fpcDownloadSpecifiedDaysOfWeek
};

Members

fpcDownloadOnce (0)
One fetch only.
fpcDownloadDaily (1)
One fetch per day.
fpcDownloadSpecifiedDaysOfWeek (2)
One fetch per each specified day of week.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcScheduleHours

The FpcScheduleHours enumerated type contains values that describe the hours of the day. Used in schedule templates.

enum FpcScheduleHours {
  fpcALL_DAY=-1,
  fpcAM_0,
  fpcAM_1,
  fpcAM_2,
  fpcAM_3,
  fpcAM_4,
  fpcAM_5,
  fpcAM_6,
  fpcAM_7,
  fpcAM_8,
  fpcAM_9,
  fpcAM_10,
  fpcAM_11,
  fpcAM_12,
  fpcPM_1,
  fpcPM_2,
  fpcPM_3,
  fpcPM_4,
  fpcPM_5,
  fpcPM_6,
  fpcPM_7,
  fpcPM_8,
  fpcPM_9,
  fpcPM_10,
  fpcPM_11
};

Members

fpcALL_DAY=-1
All hours of the day.
fpcAM_0
Midnight.
fpcAM_1
1 A.M.
fpcAM_2
2 A.M.
fpcAM_3
3 A.M.
fpcAM_4
4 A.M.
fpcAM_5
5 A.M.
fpcAM_6
6 A.M.
fpcAM_7
7 A.M.
fpcAM_8
8 A.M.
fpcAM_9
9 A.M.
fpcAM_10
10 A.M.
fpcAM_11
11 A.M.
fpcAM_12
12 A.M.
fpcPM_1
1 P.M.
fpcPM_2
2 P.M.
fpcPM_3
3 P.M.
fpcPM_4
4 P.M.
fpcPM_5
5 P.M.
fpcPM_6
6 P.M.
fpcPM_7
7 P.M.
fpcPM_8
8 P.M.
fpcPM_9
9 P.M.
fpcPM_10
10 P.M.
fpcPM_11
11 P.M.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcSecurityScope

Information not available for this release.

enum FpcSecurityScope {
  fpcEnterprisePoliciesScope,
  fpcEnterprisePolicyScope,
  fpcSingleArrayScope,
  fpcAlertsScope,
  fpcSessionsScope
};

Members

fpcEnterprisePoliciesScope
TBD
fpcEnterprisePolicyScope
TBD
fpcSingleArrayScope
TBD
fpcAlertsScope
TBD
fpcSessionsScope
TBD

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcServices

The FpcServices enumerated type assigns numerical values for various components of ISA.

enum FpcServices {
  fpcFwSrvSvc,
  fpcW3ProxySvc,
  fpcAllServices
};

Members

fpcFwSrvSvc
The Firewall service component.
fpcW3ProxySvc
The Web proxy service component.
fpcAllServices
All the above values combined using the OR operator.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcSessionsAccessRights

Information not available for this release.

enum FpcSessionsAccessRights {
  fpcSessionsRight_Delete                 = 0x10000,
  fpcSessionsRight_Read_Control           = 0x20000,
  fpcSessionsRight_Write_Dac              = 0x40000,
  fpcSessionsRight_Write_Owner            = 0x80000,
  fpcSessionsRight_Synchronize            = 0x100000,
  fpcSessionsRight_Access_System_Security = 0x1000000,
  fpcSessionsRight_Generic_Read           = 0x80000000,
  fpcSessionsRight_Generic_Write          = 0x40000000,
  fpcSessionsRight_Generic_Execute        = 0x20000000,
  fpcSessionsRight_Generic_All            = 0x10000000,
  fpcSessionsRight_Read                   = 0x00000001,
  fpcSessionsRight_Stop                   = 0x00000002
};

Members

fpcSessionsRight_Delete
TBD
fpcSessionsRight_Read_Control
TBD
fpcSessionsRight_Write_Dac
TBD
fpcSessionsRight_Write_Owner
TBD
fpcSessionsRight_Synchronize
TBD
fpcSessionsRight_Access_System_Security
TBD
fpcSessionsRight_Generic_Read
TBD
fpcSessionsRight_Generic_Write
TBD
fpcSessionsRight_Generic_Execute
TBD
fpcSessionsRight_Generic_All
TBD
fpcSessionsRight_Read
TBD
fpcSessionsRight_Stop
TBD


FpcSSLClientCertificateMode

The FpcSSLClientCertificateMode enumerated type contains values that describe Web-publishing rule parameters defining if client certification is allowed, ignored or required.

enum FpcSSLClientCertificateMode {
  fpcSSLIgnoreClientCertificate,
  fpcSSLAcceptClientCertificate,
  fpcSSLRequireClientCertificate
};

Members

fpcSSLIgnoreClientCertificate
Client certificate is ignored.
fpcSSLAcceptClientCertificate
Client certificate is accepted.
fpcSSLRequireClientCertificate
Client certificate is required.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcSSLRequireSecureChannelMode

The FpcSSLRequireSecureChannelMode enumerated type contains values that describe Web-publishing rule parameters that defining whether an SSL connection is required and, if so, the type of connection.

enum FpcSSLRequireSecureChannelMode {
  fpcSSLDontRequireSecureChannel,
  fpcSSLRequireSecureChannel,
  fpcSSLRequire128BitSecureChannel
};

Members

fpcSSLDontRequireSecureChannel
Doesn't require secure channel.
fpcSSLRequireSecureChannel
Requires secure channel.
fpcSSLRequire128BitSecureChannel
Requires secure channel using 128-bit encryption.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcTimeScale

The FpcTimeScale enumerated type contains values that describe time ranges used in cache interval units.

enum FpcTimeScale {
  fpcTimeInSeconds =1,
  fpcTimeInMinutes,
  fpcTimeInHours,
  fpcTimeInDays,
  fpcTimeInWeeks
};

Members

fpcTimeInSeconds
Time in seconds.
fpcTimeInMinutes
Time in minutes.
fpcTimeInHours
Time in hours.
fpcTimeInDays
Time in days.
fpcTimeInWeeks
Time in weeks.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


Administration Object Error Codes

The following are the COM object error codes, defined in CometErrorCodes.h.

Message ID | Code | Text | Explanation
E_MSP_LOGON_FAILURE | COMET_ERR(0x200) |  |
E_MSP_LOCALSERVER_UNREACHABLE | COMET_ERR(0x201) |  |
E_MSP_LOCALVERSION_CONFLICT | COMET_ERR(0x202) |  |
E_MSP_ARRAYDATA_UNINITIALIZED | COMET_ERR(0x203) |  |
E_MSP_ARRAY_ACCESS_DENIED | COMET_ERR(0x204) |  |
E_MSP_ARRAY_VERSION_CONFLICT | COMET_ERR(0x205) |  |
E_MSP_LOCALSERVER_ABSENT | COMET_ERR(0x206) |  |
E_MSP_BAD_PROXY_ENVIRONMENT | COMET_ERR(0x207) |  |
E_MSP_JOINSERVER_UNREACHABLE | COMET_ERR(0x208) |  |
E_MSP_JOINVERSION_CONFLICT | COMET_ERR(0x209) |  |
E_MSP_NOMORE_ARRAYMEMBERS | COMET_ERR(0x210) |  |
E_MSP_ALREADY_MEMBER | COMET_ERR(0x211) |  |
E_MSP_CORRUPT_JOINLIST | COMET_ERR(0x213) |  |
E_MSP_SERVER_NOT_MEMBER | COMET_ERR(0x212) |  |
E_MSP_SERVER_NOT_FOUND) | COMET_ERR(0x214 |  |
E_MSP_SELECTED_SERVER_UNAVAILABLE | COMET_ERR(0x215) |  |
E_MSP_SELECTED_SERVER_ALONE | COMET_ERR(0x216) |  |
E_MSP_LOCALSERVER_UPDATE_ERROR | COMET_ERR(0x217) |  |
E_MSP_LOCALSERVER_UPDATE_SINGLE | COMET_ERR(0x218) |  |
#define E_MSP_SYNCHRONIZATION_FAILED | COMET_ERR(0x219) |  |
E_MSP_JOINSERVER_NOT_SYNCHRONIZED | COMET_ERR(0x220) |  |
E_MSP_CANNOT_JOIN_SELF | COMET_ERR(0x221) |  |
E_MSP_MEMBERLIST_UNINITIALIZED | COMET_ERR(0x222) |  |
E_MSP_NOJOIN_DONE | COMET_ERR(0x223) |  |
E_MSP_INVALID_ENUM_CONTEXT | COMET_ERR(0x224) |  |
E_MSP_ARRAY_OP_IN_PROGRESS | COMET_ERR(0x225) |  |
E_MSP_ODBC_ERROR | COMET_ERR(0x226) |  |
E_MSP_INCORRECT_ADDR_MODE | COMET_ERR(0x227) |  |
E_MSP_BAD_ADMIN_ROOT | COMET_ERR(0x228) |  |
E_MSP_PROTOCOL_WITH_NO_NAME | COMET_ERR(0x229) |  |
E_MSP_CACHE_FILTER_ERR1 | COMET_ERR(0x22a) |  |
E_MSP_CACHE_FILTER_ERR2 | COMET_ERR(0x22b) |  |
E_MSP_CACHE_FILTER_ERR3 | COMET_ERR(0x22c) |  |
E_MSP_CACHE_FILTER_ERR4 | COMET_ERR(0x22d) |  |
E_MSP_URL_FORMAT_BAD | COMET_ERR(0x22e) |  |
E_INIT_NOT_BEEN_CALLED | COMET_ERR(0x22f) |  |
E_REFRESH_NOT_BEEN_CALLED | COMET_ERR(0x230) |  |
E_NO_EXTERNAL_NIC | COMET_ERR(0x231) |  |
E_DEST_NOT_IP | COMET_ERR(0x232) |  |
E_DEST_NOT_MASK | COMET_ERR(0x233) |  |
E_DEST_NOT_DOMAIN | COMET_ERR(0x234) |  |
E_NO_COMET_STORAGE | COMET_ERR(0x235) |  |
E_COMET_OBJECT_INVALID | COMET_ERR(0x236) |  |
E_COMET_STRING_BAD | COMET_ERR(0x237) |  |
E_EVENT_NOT_DEFINED | COMET_ERR(0x238) |  |
E_NON_REMOVAL_EVENT | COMET_ERR(0x239) |  |
E_ALERT_KEY_INVALID | COMET_ERR(0x23a) |  |
E_CANNOT_DEL_DEFAULT_RULE | COMET_ERR(0x23b) |  |
E_CANNOT_MOVE_DEFAULT_RULE | COMET_ERR(0x23c) |  |
E_CANT_CHANGE_DEFUALT_RULE_DESCRIPTION | COMET_ERR(0x23d) |  |
E_CANT_CHANGE_DEFUALT_RULE_ENABLE | COMET_ERR(0x23e) |  |
E_COMET_CORRUPTED_OBJECT_DATA | COMET_ERR(0x23f) |  |
E_COMET_BAD_DESTINATION_SET_NAME | COMET_ERR(0x240) |  |
E_COMET_BAD_SCHEDULE_TEMPLATE_NAME | COMET_ERR(0x241) |  |
E_COMET_INVALID_SERVER_NAME | COMET_ERR(0x242) |  |
E_COMET_STRING_CONTAINS_INVALID_CHARACTERS | COMET_ERR(0x243) |  |
E_COMET_EMPTY_STRING | COMET_ERR(0x244) |  |
E_COMET_STRING_TOO_LONG | COMET_ERR(0x245) |  |
E_COMET_BAD_PROTOCOL_NAME | COMET_ERR(0x246) |  |
E_COMET_VALUE_TOO_LARGE | COMET_ERR(0x247) |  |
E_COMET_VALUE_TOO_SMALL | COMET_ERR(0x248) |  |
E_COMET_CREATE_CHILD_INSTANCE_FAILED | COMET_ERR(0x249) |  |
E_COMET_COMPONENT_NOT_INSTALLED | COMET_ERR(0x24a) |  |
E_COMET_IDS_BAD_IP_FORMAT | COMET_ERR(0x24b) |  |
E_COMET_IP_FROM_MORE_THAN_TO | COMET_ERR(0x24c) |  |
E_COMET_IP_PAIR_ALREADY_EXISTS | COMET_ERR(0x24d) |  |
E_COMET_INVALID_BANDWIDTH_RATE | COMET_ERR(0x24e) |  |
E_COMET_BAD_BANDWIDTH_CLASS_NAME | COMET_ERR(0x24f) |  |
E_COMET_ALERT_MUST_HAVE_ACTIONS | COMET_ERR(0x250) |  |
E_FAILED_TO_READ_DISK_SIZE_AND_TYPE | COMET_ERR(0x251) |  |
E_ITEM_IS_USED_IN_RULE | COMET_ERR(0x252) |  |
E_COMET_ALERT_ALREADY_DEFINED | COMET_ERR(0x253) |  |
S_COMETLOG_BAD_COLUMN_SELECTION | (MAKE_HRESULT(SEVERITY_SUCCESS, FACILITY_ITF, 0x254)) |  |
E_COMET_REDIRECT_EMPTY | COMET_ERR(0x255) |  |
E_COMET_EXTERNAL_REF_EXIST | COMET_ERR(0x256) |  |
E_COMET_BAD_DOMAIN | COMET_ERR(0x257) |  |
E_COMET_ARRAY_NOT_EMPTY | COMET_ERR(0x258) |  |
E_COMET_MUST_USE_DS | COMET_ERR(0x259) |  | This functionality required Active Directory™ as ISA storage.
E_COMET_NAME_IN_PENDING_REMOVE | COMET_ERR(0x25a) |  |
E_COMET_INVALID_CPID | COMET_ERR(0x25b) |  |
E_COMET_DEL_DEFAULT_POLICY | COMET_ERR(0x25c) |  | The default policy cannot be removed.
E_COMET_DEL_USED_POLICY | COMET_ERR(0x25d) |  | The policy is in use by some arrays and cannot be removed.
E_COMET_NO_LOGGING_FOR_ALLOW_PF | COMET_ERR(0x25e) |  |
E_COMET_ARRAY_ALREADY_PROMOTED | COMET_ERR(0x25f) |  |
E_COMET_NO_DS_CONNECTION | COMET_ERR(0x260) |  |
E_COMET_CANT_MOVE_TO_STANDALONE_ARRAY | COMET_ERR(0x261) |  |
E_COMET_ALLREADY_HAVE_DS_CONNECTION | COMET_ERR(0x262) |  |
E_COMET_REMOTE_SERVER_UNAVAILABLE | COMET_ERR(0x263) |  |
E_COMET_DCOM_CONNECTION_FAILED | COMET_ERR(0x264) |  |
E_COMET_SERVER_ALLREADY_CONNECTED | COMET_ERR(0x265) |  |
E_COMET_NOT_IN_GLOBAL | COMET_ERR(0x266) |  | The property is not available for global settings.
E_COMET_EVENT_IN_USE | COMET_ERR(0x267) |  |
E_LAT_ENTRY_ALREADY_EXISTS | COMET_ERR(0x268) |  |
E_COMET_IP_NOT_INTERNAL | COMET_ERR(0x269) |  |
E_COMET_IP_NOT_EXTERNAL | COMET_ERR(0x270) |  |
E_COMET_MISSING_PROPS | COMET_ERR(0x271) |  |
E_COMET_PNAT_INTERNAL_SLOT_USED | COMET_ERR(0x272) |  |
E_COMET_PNAT_EXTERNAL_SLOT_USED | COMET_ERR(0x273) |  |
E_COMET_PNAT_PROTOCOL_NOT_INBOUND | COMET_ERR(0x274) |  |
E_COMET_ARRAY_NO_POLICY | COMET_ERR(0x275) |  | There must be at least one active policy (either local or enterprise) for an array.
E_COMET_ALLOWRULE_WITH_ENTERPRISE | COMET_ERR(0x276) |  | Cannot set rule action to Allow when global policy is active.
E_COMET_ADDRULE_NOLOCAL | COMET_ERR(0x277) |  | Cannot add rule: Local policy is not allowed.


Firewall Reference

The firewall reference provides information on the interfaces, enumerated types, and structures you will use in the development of application filters.

This section contains the following topics:

  • Filter Interfaces
  • Structures


Filter Interfaces

FIlter interfaces expose the COM objects needed to develop application filters.

Each administration object also implements an interface that can be used by C++ programmers. Those interfaces are documented on the reference pages for the administration COM objects.

This section contains the following filter interfaces:

  • IFWXAcceptCompletion
  • IFWXConnection
  • IFWXDataFilter
  • IFWXExternalIOCompletion
  • IFWXFilter
  • IFWXFilterAdmin
  • IFWXGetXByY
  • IFWXImpersonator
  • IFWXIOBuffer
  • IFWXIOCompletion
  • IFWXNetworkSocket
  • IFWXOverlapped
  • IFWXProxy
  • IFWXProxyAction
  • IFWXSession
  • IFWXSessionFilter
  • IFWXSlowDataFilter
  • IFWXSocket


IFWXAcceptCompletion

The IFWXAcceptCompletion interface receives notifications when an asynchronous input/output (I/O) accept operation on an IFWXNetworkSocket interface is completed using the IFWXNetworkSocket::Accept method.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXAcceptCompletion Methods | Description
CompleteAsyncAccept | Receives notifications when the IFWXNetworkSocket::Accept method completes.

Implementation

This interface is implemented by the Firewall service.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXNetworkSocket::Accept


IFWXAcceptCompletion::CompleteAsyncAccept Method

This method is called when the IFWXNetworkSocket::Accept method completes.

HRESULT CompleteAsyncAccept(
  BOOL fSuccess,
  DWORD Win32ErrorCode,
  INetworkSocket * pListeningSocket,
  INetworkSocket * pAcceptSocket,
  LPSOCKADDR RemoteAddress,
  DWORD RemoteAddressLength,
  LPSOCKADDR LocalAddress,
  DWORD LocalAddressLength,
  UserContextType UserData
);

Parameters

fSuccess
[in] Success flag. If TRUE, the IFWXNetworkSocket::Accept method succeeded. If FALSE, it failed.
Win32ErrorCode
[in] Win32 error code. This parameter is defined only if the fSuccess parameter is FALSE.
pListeningSocket
[in] Pointer to the IFWXNetworkSocket interface on the listening socket.
pAcceptSocket
[in] Pointer to the IFWXNetworkSocket interface on the newly accepted connection.
RemoteAddress
[in] Pointer to a sockaddr structure that contains the remote address of the connection. This is the same information that would be returned by the Windows Sockets (Winsock) getpeername function.
RemoteAddressLength
[in] Size, in bytes, of the buffer pointed to by the RemoteAddress parameter.
LocalAddress
[in] Pointer to a sockaddr structure that contains the local address of the connection. This is the same information that would be returned by the Winsock getsockname function.
LocalAddressLength
[in] Size, in bytes, of the buffer to which the LocalAddress parameter points.
UserData
[in] The UserData parameter that was passed to the IFWXNetworkSocket::Accept method.

Return Values

Value | Meaning
S_OK | The connection will be denied.

Any error should be handled with this method.

Remarks

The UserData parameter provides a context to the notification. You can use the same notification interface for completion notifications from distinct network socket objects and differentiate among them by using different values for UserData.


IFWXConnection

The IFWXConnection interface implements functions specific to a particular connection.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXConnection Methods | Description
AttachDataFilter | Sets up a data filter for a connection.
AttachDataFilterWithDestination | Sets up a data filter that is valid only for a specific UDP destination.
EmulateConnection | Makes a connection to a client after emulating a bind method.
SetSocketName | Sets the socket name for an emulated bind.
Kill | Forces the connection to terminate.
GetExternalSocketName | Gets the socket name for the external side of the connection.
SetClientAddress | Gives the client address for a connection returned by the IFWXSession::BindForClient method, for which the client address was not previously specified.
SetProtocol | Associates the connection object with a specified protocol.
Deny | Denies the current operation.
SetBufferSize | Sets the buffer size for a connection.
GetExternalPeerName | Gets the peer name for the external side of the connection.
GetSession | Returns the session object to which a connection belongs.

Implementation

This interface is implemented by the Firewall service.

Remarks

The connection object represented by the IFWXConnection interface implements functions specific to a particular connection. Every remote socket created on behalf of a client has a connection object associated with it.

A single TPC connection between a listening socket on the Firewall service and an external server may result in the creation of two connection objects: listening on the Firewall service, and inbound. When the remote server disconnects, the inbound connection is closed, but the listening connection may not close, if the FWX_FLAG_ALLOW_MULTIPLE was specified.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXConnection::AttachDataFilter Method

Attaches a data filter to this connection.

HRESULT AttachDataFilter(
  IFWXDataFilter * piDataFilter,
  DataFilterPriorityClass PriorityClass,
  IUnknown * punkFilterContext
);

Parameters

piDataFilter
[in] Pointer to the IFWXDataFilter interface of the Firewall service data filter object to use with this connection.
PriorityClass
[in] Priority class for the data filter. This determines the position of the data filter in relation to other data filters that may be attached to the connection. This parameter is a value from the FwxDataFilterPriorityClass enumeration.
punkFilterContext
[in] Pointer to the interface to use to pass contextual information to the data filter, such as the session to which the data filter is being attached. This interface is passed to the IFWXDataFilter::SetSockets method, in the punkFilterContext parameter. This parameter can be NULL.

Remarks

This method can be called only in the context of the IFWXSessionFilter::FwxProxyEventHandler method while handling events with one of the following values:

fwx_AcceptedConnection

fwx_Bind_Udp

fwx_Connect_Tcp

fwx_Udp_Destination


IFWXConnection::AttachDataFilterWithDestination Method

Attaches a data filter to this connection. The data filter is associated with a remote destination.

HRESULT AttachDataFilterWithDestination(
  IFWXDataFilter * piDataFilter,
  DataFilterPriorityClass PriorityClass,
  IUnknown * punkFilterContext,
  LPSOCKADDR ExternalAddress,
  INT ExternalAddressLength
);

Parameters

piDataFilter
[in] Pointer to the IFWXDataFilter interface on the data filter to use with this connection.
PriorityClass
[in] Priority class for the data filter. This determines the position of the data filter in relation to other data filters that may be attached to the connection. This parameter is a value from the FwxDataFilterPriorityClass enumeration.
punkFilterContext
[in] Pointer to the interface to use to pass context information to the data filter. This interface is passed to the IFWXDataFilter::SetSockets method. This parameter can be NULL.
ExternalAddress
[in] Pointer to a sockaddr structure that contains the address of the peer of UDP datagrams for which the data filter is installed.

The data filter receives all datagrams sent through the connection, but is removed if and when the service causes a destination to expire.

ExternalAddressLength
[in] Length, in bytes, of the ExternalAddress parameter.

Remarks

This method must be called only in the context of the IFWXSessionFilter::FwxProxyEventHandler method while handling an event of type fwx_Udp_Destination. This method would be used when you want the filter to attach only to data from a specific destination, even if the connection is not destination specific, as is the case for UDP connections.


IFWXConnection::Deny Method

Denies the current operation on the connection object.

HRESULT Deny(
  DWORD Reserved
);

Parameters

Reserved
[in] Reserved for future use. Must be zero.

Return Values

Value | Meaning
S_OK | The connection will be denied.
E_INVALIDARG | Invalid value was passed to the Reserved parameter
FWX_E_BAD_CONTEXT | The method was not called while handling any of the supported events.

Remarks

This method is rarely used. Using "Protocol Rules" and "Site and Content Rules" administration methods is the preferred way to control user activity.

This method must only be called in the context of the IFWXSessionFilter::FwxProxyEventHandler method while handling events with one of the following values:

fwx_AcceptedConnection

fwx_Bind_Udp

fwx_Bind_Tcp

fwx_Connect_Tcp

fwx_Udp_Destination

The action that caused the event will be canceled. A bind operation will fail with error code 10048 (WSAEADDRINUSE), a connect operation will fail with error code 10061 (WSAECONNREFUSED). An accepted connection will be aborted, and outbound UDP packets sent to a denied destination will be discarded.


IFWXConnection::EmulateConnection Method

Creates a connection to a client for a filter-emulated listening connection.

HRESULT EmulateConnection(
  IFWXDataFilter * piDataFilter,
  LPSOCKADDR RemoteAddress,
  DWORD RemoteAddressLength,
  LPSOCKADDR LocalAddress,
  DWORD LocalAddressLength,
  IFWXConnection ** ppNewIFWXConnection
);

Parameters

piDataFilter
[in] Pointer to the IFWXDataFilter interface on the data filter that supplies the data for the connection. The data filter is installed with fwx_dfpc_Emulation priority, which is closest to the Internet. The data filter only receives an interface of an internal socket. An external socket is assumed to be held by the caller.
RemoteAddress
[in] Pointer to a sockaddr structure that contains the address of the remote socket that is connecting to the client. This address is set in the output parameter of accept and getpeername functions on the client.
RemoteAddressLength
[in] Length, in bytes, of the RemoteAddress parameter.
LocalAddress
[in] Pointer to a sockaddr structure that contains the local proxy address that is used for the connection. This is the address that the getsockname function returns to the client.
LocalAddressLength
[in] Length, in bytes, of the LocalAddress parameter.
ppNewIFWXConnection
[out] Pointer to a variable that receives an IFWXConnection interface pointer on the connection object that is created for this new connection. The parameter can be NULL. The reference to the new connection object must not be held after a fwx_ConnectionTerminating event for that connection is received.

Remarks

This method may be called only if this connection is in the listening state, and the caller is a filter that is emulating the listening state for the connection. Clients use the emulated connection, so that, effectively, only one real connection is used.


IFWXConnection::GetExternalPeerName Method

Gets the peer name for the external socket. This method is implemented by calling the Winsock getpeername function on the actual external socket.

HRESULT GetExternalPeerName(
  LPSOCKADDR Address,
  LPINT AddressLength
);

Parameters

Address
[out] Pointer to a sockaddr structure that receives the peer name.
AddressLength
[in, out] On input, this parameter specifies the size, in bytes, of the Address buffer. On output, it receives the size, in bytes, needed to hold the address.

Remarks

When the proxy is chained to another proxy, this function returns the value for the last proxy in the chain.


IFWXConnection::GetExternalSocketName Method

Gets the socket name for the external socket. This method is implemented by calling the Winsock getsockname function on the actual external socket.

HRESULT GetExternalSocketName(
  LPSOCKADDR Address,
  LPINT AddressLength
);

Parameters

Address
[out] Pointer to a sockaddr structure that receives the socket address (name).
AddressLength
[in, out] On input, this parameter specifies the size, in bytes, of the Address buffer. On output, it receives the size, in bytes, needed to hold the address.

Remarks

When the proxy is chained to another proxy, this function returns the value for the last proxy in the chain.


IFWXConnection::GetSession Method

Returns the session object to which a connection belongs.

HRESULT GetSession(
  IFWXSession *ppSession
);

Parameters

pSession
[out] Pointer to the session object.

Return Values

Value | Meaning
S_OK | The method succeeded.
FWX_E_TERMINATING | The socket is already closed.


IFWXConnection::Kill Method

Forces the connection to terminate.

HRESULT Kill()

Remarks

This method could be used to allow an administrator to end a group of connections.


IFWXConnection::SetBufferSize Method

Sets the buffer size for a connection.

HRESULT SetBufferSize(
  DWORD BufferSize
);

Parameters

BufferSize
[in] Buffer size to be used for this connection.

Return Values

Value | Meaning
S_OK | The connection will be denied.
E_INVALIDARG | Invalid value was passed to the method.

Remarks

This method allows you to modify the buffer size for a connection. By default, the service uses buffers of 4096 bytes for UDP and 2048 for TCP. UDP datagrams larger than the default buffer size are dropped by the service. Use this function to set a larger buffer size for protocols that use packets larger than 4096 bytes.

For TCP, the buffer size is used for optimization. In general, it should not be modified. For UDP, datagrams larger than the buffer size can be dropped. If the filter determines that larger datagrams can be transmitted, it should set the buffer accordingly.


IFWXConnection::SetClientAddress Method

Gives the client address for a connection returned by the IFWXSession::BindForClient method for which the client address was not previously specified.

HRESULT SetClientAddress(
  LPSOCKADDR ClientAddress,
  DWORD ClientAddressLength
);

Parameters

ClientAddress
[in] Pointer to a sockaddr structure that contains the address that the client used.
ClientAddressLength
[in] Length, in bytes, of the ClientAddress parameter.

Return Values

Value | Meaning
S_OK | The connection will be denied.
E_INVALIDARG | Invalid address passed to the method, or the client address was already specified.
HRESULT_FROM_WIN32(win32 error code) | Windows Sockets (Winsock) or Win32 error code. The method failed.


IFWXConnection::SetProtocol Method

Attempts to associate the connection object with the specified protocol.

HRESULT SetProtocol(
  REFGUID ProtocolGuid,
  DWORD dwFlags
);

Parameters

ProtocolGuid
[in] GUID of the protocol to attempt to associate with the connection.
dwFlags
[in] This flag parameter can be a combination of the following values:
Value | Description
FWX_FLAG_EMULATE_PROTOCOL Indicates that the filter intends to emulate the connection if this call is successful.

For UDP and outbound TCP connections, a filter that specifies this flag must attach a data filter with fwx_dfpc_Emulation priority if the method call succeeds.

For inbound TCP connections, a filter must call the IFWXConnection::EmulateConnection method in order to attach a data filter.
0 | The filter will not emulate the connection.

Return Values

Value | Meaning
S_OK | The operation completed successfully.
FWX_E_PROTOCOL_RULES_DENIED | The protocol rules do not allow the user to use the protocol specified by the ProtocolGuid parameter.
FWX_E_ALREADY_EMULATED | The connection is already emulated by another filter.

Remarks

This method must be called only in the context of the IFWXSessionFilter::FwxProxyEventHandler method while handling an event of type fwx_Udp_Destination or fwx_Connect_Tcp. The method checks the user permissions for the protocol, and then attempts to associate the connection with the protocol based on those permissions.


IFWXConnection::SetSocketName Method

Sets the name of the socket for the connection. Call this method only if the caller is emulating the connection.

HRESULT SetSocketName(
  LPSOCKADDR Address,
  DWORD AddressLength
);

Parameters

Address
[in] Pointer to a sockaddr structure that contains the socket address.
AddressLength
[in] Length, in bytes, of the Address parameter.

Remarks

On regular connections, the Firewall service calls the getsockname Winsock function on the external socket, and passes this information to the Firewall client. For an emulated connection there is no external socket, or the external socket is known only to the filter. The filter is required to call this method and set the socket name.

When there is no connection, it is advisable to return an IP address of the Firewall service (external or internal as appropriate) because the client application may use this information to publish the address.


IFWXDataFilter

A filter must implement the IFWXDataFilter interface to hook into the data pump of the Firewall service.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXDataFilter Methods | Description
SetSockets | Gives the data filter the socket interfaces it should use.
Detach | Orders the data filter to release the references it holds to the sockets.

Implementation

This interface is implemented by the application filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXDataFilter::Detach Method

Detaches a data filter. When a data filter is detached it must release the references it holds to the socket interfaces and to the connection.

HRESULT Detach()

Return Values

Value | Meaning
S_OK | The method succeeded. S_OK must be returned by this method. Any error should be handled in this method.

Remarks

This method may be called before the SetSockets method, to ensure cleanup in case of failures.


IFWXDataFilter::SetSockets Method

Sets the internal and external sockets for the data filter. When this function is called, the filter is expected to begin the data-pumping process between the sockets.

HRESULT SetSockets(
  IFWXSocket * piInternalSocket,
  IFWXSocket * pIExternalSocket,
  IFWXConnection * piConnection,
  IFWXUnknown * punkFilterContext
);

Parameters

piInternalSocket
[in] Pointer to the IFWXSocket interface for an internal socket.
pIExternalSocket
[in] Pointer to the ISocket interface for an external socket.
piConnection
[in] Pointer to the IFWXConnection interface on the connection object on which this data filter is installed.
punkFilterContext
[in] Pointer to the interface used to pass context information to the data filter. The parameter will have the same value as the punkFilterContext parameter of IFWXConnection::AttachDataFilter and IFWXSession::SetDataFilterFactory.

Return Values

Value | Meaning
S_OK | The method succeeded.
E_OUTOFMEMORY | Insufficient memory or resources to process the event. The connection will be terminated.

Remarks

A filter that is emulating a connection receives NULL for the external socket interface.


IFWXExternalIOCompletion

The IFWXExternalIOCompletion interface is the notification interface for Win32 input/output (I/O) operations for which the filter has a handle.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXExternalIOCompletion Methods | Description
CompleteAsyncIO | Receives notifications from the firewall service when a Win32 I/O operation completes.

Implementation

This interface is implemented by the Firewall service.

Remarks

This interface is similar in function to the IFWXIOCompletion interface, but is used to call or write to Win32 files asynchronously.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXProxy::HookToCompletionPort, IFWXProxy::CreateOverlapped, IFWXOverlapped


IFWXExternalIOCompletion::CompleteAsyncIO Method

Called by the firewall service when a Win32 I/O operation completes.

HRESULT CompleteAsyncIO(
  BOOL fSuccess,
  DWORD NumberOfBytesTransfered,
  DWORD Win32ErrorCode,
  IFWXOverlapped * pOverlapped,
  UserContextType UserData
);

Parameters

fSuccess
[in] Success flag. If TRUE, the I/O operation succeeded. If FALSE, it failed.
NumberOfBytesTransfered
[in] Number of bytes transferred during a successful I/O operation.
Win32ErrorCode
[in] Win32 error code for a failed I/O operation.
pOverlapped
[in] Pointer to the IFWXOverlapped interface on the overlapped object used for this operation.
UserData
[in] The UserData parameter set in the call to the IFWXOverlapped::SetNotificationInterface method.

Remarks

The UserData parameter provides a context to the notification. You can use the same notification interface for completion notifications from distinct network socket objects and differentiate between them using different values for UserData.


IFWXFilter

The Firewall service uses the IFWXFilter interface to load and initialize a filter, and to create session filters. An IFWXFilter interface is called for each filter that is in ISA storage and is enabled.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXFilter Methods | Description
FilterInit | Called by the Firewall service when the filter is starting.
FilterShutdown | Called by the Firewall service when the service is stopping.
AttachToSession | Called by the Firewall service when it determines that a session filter is needed.

Implementation

This interface is implemented by the application filter.

Remarks

This is the interface that is used to create the filter object, therefore every filter must initially implement this interface. Only one instance of the IFWXFilter object is created per filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXFilter::AttachToSession Method

Creates a session filter object when the Firewall service detects an event for which the filter is registered. AttachToSession also indicates the set of events that the session filter will handle. This set of events is a subset of the events requested in FilterInit. The events for which the filter is registered are received in a FWXFilterHookEvents structure.

The Firewall service object calls this interface when it detects an event for which the filter is registered.

HRESULT AttachToSession(
  IFWXSession * piSession,
  IFWXSessionFilter ** piSessionFilter,
  PFilterHookEvents * ppFilterHookEvents
);

Return Values

Value | Meaning
S_OK | The method succeeded.
E_OUTOFMEMORY | Insufficient memory or resources to process the event. This will cause the request that generated the event to fail.

Parameters

piSession
[in] Pointer to the IFWXSession interface associated with the session to be monitored.
piSessionFilter
[out] Address of a variable that receives a pointer to the IFWXSessionFilter interface on the session filter object. The session filter object receives event notifications for the session.
ppFilterHookEvents

[out] Pointer to a PFilterHookEvents variable. This must be set to refer to a FwxFilterHookEvents structure containing the initial set of events that the filter monitors. Use the CoTaskMemAlloc function to allocate the structure. IFWXProxy::DuplicateFilterHookEvents creates a duplicate of the FwxFilterHookEvents structure in a buffer which can be returned by IFWXFilter::AttachToSession.

See Also

IFWXProxy::DuplicateFilterHookEvents


IFWXFilter::FilterInit Method

Initializes the filter and passes it an interface pointer to the Firewall service object. The Firewall service object provides general methods to the filter. For a list of the general methods see IFWXProxy, the interface for the Firewall service object.

HRESULT FilterInit(
  IFWXProxy * pIFWXProxy,
  PFilterHookEvents * ppFilterHookEvents
);

Parameters

pIFWXProxy
[in] Pointer to the IFWXProxy interface on the firewall service. IFWXProxy provides access to proxy services.
ppFilterHookEvents
[out] Pointer to a PFilterHookEvents variable. This must be set to refer to a FwxFilterHookEvents structure containing the initial set of events that the filter monitors. Use the CoTaskMemAlloc function to allocate the structure. IFWXProxy::DuplicateFilterHookEvents creates a duplicate of the FwxFilterHookEvents structure in a buffer which can be returned by IFWXFilter::AttachToSession.

Return Values

Value | Meaning
S_OK | The connection will be denied.
FAILED | The connection is aborted.

Remarks

Place in FilterInit all initializations, particularly events to monitor, as well as the reading of configurations and the creation of listening sockets.

See Also

IFWXProxy::DuplicateFilterHookEvents


IFWXFilter::FilterShutdown Method

Begins the shutdown sequence for the filter object when the Firewall service is shutting down.

HRESULT FilterShutdown()

Return Values

Value | Meaning
S_OK | The connection will be denied.

Any error should be handled in this method.

Remarks

When shutting down the filter, the Firewall service releases references to all filter-implemented objects, after first making calls to the Detach method where applicable (either IFWXSessionFilter::Detach or IFWXDataFilter::Detach). However, because of the asynchronous nature of the proxy, the order of calling Detach/IFWXFilter::FilterShutdown is undefined, and the Firewall service may call the Detach method after IFWXFilter::FilterShutdown is returned. When the Firewall service calls Detach after IFWXFilter::FilterShutdown has been returned, filter-implemented objects may still be in the process of shutting down. Typically, the shutdown of filter-implemented objects does not have to be considered in filter design because the shutdown of objects occurs in the context of proxy worker threads. When the service stops, the Firewall service waits until all its worker threads have terminated and the shutdown operations have completed.

However, if the filter is doing shutdown work in a context other than a proxy worker thread — for example, a remote procedure call (RPC) worker thread or a timer callback thread — the nonproxy thread may execute code after all proxy worker threads have ended. Thus, the nonproxy thread will not have an appropriate context in which to execute the code. To avoid this situation, FilterShutdown must not be returned until all shutdown work has completed in the nonproxy worker thread contexts.


IFWXFilterAdmin

The IFWXFilterAdmin interface is used by filter setup to install and configure the filter.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXFilterAdmin Methods | Description
InstallFilter | Installs a filter.
UninstallFilter | Uninstalls a filter.
RegisterProtocolForFilter | Registers a protocol that is controlled by a filter.
UnregisterProtocolForFilter | Unregisters a protocol that is controlled by a filter.
GetProtocol | Gets a previously defined protocol.
GetParameterSets | Gets an interface that provides access to the filter's set of parameters.
GetFilterParameterSet | Gets an interface that provides access to the filter's private configuration parameter set.
GetPlugin | Gets the IFPCApplicationFilter interface, which provides access to information about the application filter configuration.

Implementation

This interface is implemented by the Firewall service.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXFilterAdmin::GetFilterParameterSet Method

Gets an interface that provides access to the filter's private configuration parameter set.

HRESULT GetFilterParameterSet(
  REFCLSID guidFilter,
  IFPCVendorParametersSet ** ppParameterSet
);

Parameters

guidFilter
[in] CLSID of the IFWXFilter object for which the parameter set is required.
ppParameterSet
[out] Address of a variable that receives the interface pointer to the parameter set.

Remarks

Each parameter set has a GUID. Use GetFilterParameterSet to get the parameter set associated with this filter, which has the same GUID as the filter.

See Also

FPCVendorParametersSet


IFWXFilterAdmin::GetParameterSets Method

Gets an interface that provides access to the collection of parameter sets.

HRESULT GetParameterSets(
  REFCLSID guidFilter,
  IFPCVendorParametersSets ** ppParameterSets
);

Parameters

guidFilter
[in] CLSID of the IFWXFilter object for which the parameter sets collection is required.
ppParameterSets
[out] Address of a variable that receives the interface pointer to the collection of parameter sets.

Remarks

Use this method to get the collection of parameter sets.

See Also

FPCVendorParametersSets


IFWXFilterAdmin::GetPlugin Method

Gets the IFPCApplicationFilter interface, which provides access to information about the application filter configuration.

HRESULT GetPlugin(
  REFCLSID guidFilter,
  IFPCApplicationFilter ** ppPlugin
);

Parameters

guidFilter
[in] Class identifier (CLSID) of an IFPCFilter object.
ppPlugin
[out] Address of a variable that receives the interface pointer to the FPCApplicationFilter object.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory or resources; method failed.

Remarks

This method can be used by a filter to monitor changes to its configuration.


IFWXFilterAdmin::GetProtocol Method

Gets the FPCFilterProtocol interface, which provides access to a protocol previously installed by IFWXFilterAdmin::RegisterProtocolForFilter.

HRESULT GetProtocol(
  REFCLSID guidFilter,
  REFGUID guidProtocol,
  IFPCFilterProtocol ** ppProtocol
);

Parameters

guidFilter
[in] CLSID of an IFWXFilter object.
guidProtocol
[in] GUID that will be used for uniquely identifying the protocol.
ppProtocol
[out] Address of a variable that receives the interface pointer to the FPCFilterProtocol object.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory or resources; method failed.

Remarks

Use this method to change the conifguration of a protocol.


IFWXFilterAdmin::InstallFilter Method

Registers the filter with ISA Server.

HRESULT InstallFilter(
  REFCLSID guidFilter,
  LPCSTR Name,
  LPCSTR Description,
  LPCSTR Vendor,
  LPCSTR VersionString,
  LPCSTR Reserved
);

Parameters

guidFilter
[in] CLSID of the IFWXFilter object to install.
Name
[in] Pointer to the short name of the filter.
Description
[in] Pointer to the description of the filter.
Vendor
[in] Pointer to the name of the company that wrote the filter.
VersionString
[in] Pointer to a string representation for the version of the filter.
Reserved
[in] Reserved for future use. Passes a null pointer.

Return Values

Value | Meaning
S_OK | The filter was installed successfully.
HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS) | The filter is already installed.

Remarks

The Firewall service uses the CLSID and priority of the filter when loading it. The name, description, vendor, and version string are used for displaying information about the filter in the ISA administration tool, and are not parsed or interpreted by the proxy.


IFWXFilterAdmin::RegisterProtocolForFilter Method

Registers a protocol controlled by a given filter. A registered protocol will appear in the ISA administration tool.

HRESULT RegisterProtocolForFilter(
  REFCLSID guidFilter,
  REFGUID guidProtocol,
  LPCSTR szProtocolName,
  LPCSTR szDescription,
  LPCSTR Reserved
);

Parameters

guidFilter
[in] CLSID of an IFWXFilter object. Each registered protocol is associated with an IFWXFilter object and is valid only when that filter is installed.
guidProtocol
[in] GUID that will be used for uniquely identifying the protocol.
szProtocolName
[in] Pointer to the name of the protocol as it is to appear in the administration tool.
szDescription
[in] Pointer to the description text for the protocol.
Reserved
Reserved for future use. Passes a null string.

Return Values

Value | Meaning
S_OK | The protocol was installed, and the filter for guidFilter is properly installed.
S_FALSE | The protocol was registered, but the filter specified by guidFilter is not installed.
Error code | The protocol registration failed.

Remarks

Protocols can be recognized directly by the Firewall service, or the filter can control the proxy's recognition of the protocol. The advantage of filter control of protocol recognition is that a filter can recognize which protocol is associated with a secondary connection, whereas the Firewall service cannot do so independently.

See Also

IFWXConnection::SetProtocol, IFWXSession::AccessCheck


IFWXFilterAdmin::UninstallFilter Method

Removes the filter registration from the ISA configuration.

HRESULT UninstallFilter(
  REFCLSID guidFilter
);

Parameters

guidFilter
[in] CLSID of the IFWXFilter object to uninstall.

Remarks

Use this method in an uninstall procedure.


IFWXFilterAdmin::UnregisterProtocolForFilter Method

Unregisters a protocol controlled by a given filter.

HRESULT UnregisterProtocolForFilter(
  REFCLSID guidFilter,
  REFGUID guidProtocol
);

Parameters

guidFilter
[in] CLSID of an IFWXFilter object. Each registered protocol is associated with an IFWXFilter object and is valid only when that filter is installed.
guidProtocol
[in] GUID of the protocol to be removed.

Return Values

Value | Meaning
S_OK | The protocol was removed successfully.
Error code | The protocol was not removed.

Remarks

Use this method in an uninstall procedure.


IFWXGetXByY

This interface allows a filter to modify the result of remote gethostbyname or gethostbyaddr calls made by a Firewall client.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXGetXByY Methods | Description
Deny | Denies the name-resolution request.
SetResult | Sets the hostent structure that will be returned.

Implementation

This interface is implemented by the Firewall service.

Remarks

The IFWXGetXByY interface essentially overrides the gethostbyname or gethostbyaddr functions, returning a hostent structure with different contents than would have been returned by the unfiltered calls. The filter has to call this interface from within IFWXSessionFilter::FwxProxyEventHandler.

A typical use of this interface would be to return an IP address other than that requested by the client; that is, to redirect the request.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXGetXByY::Deny Method

Denies the name-resolution request.

HRESULT Deny(
  DWORD Reserved
);

Parameters

Reserved
Reserved for future use. Must be zero.

Return Values

Value | Meaning
S_OK | The Deny method succeeded.
FWX_E_TERMINATING | The IFWXGetXByY object is no longer valid.

Remarks

FWX_E_TERMINATING would be returned if the filter called this interface from any point other than within the IFWXSessionFilter::FwxProxyEventHandler function, because IWspGetXByY can no longer affect the results.

See Also

FwxGetHostByAddrEvent, FwxGetHostByNameEvent


IFWXGetXByY::SetResult Method

Overrides the name resolution result with the specified hostent structure.

HRESULT SetResult(
  LPHOSTENT Hostent
);

Parameters

Hostent
[in] Pointer to a buffer containing a hostent structure that will be returned to the client.

Return Values

Value | Meaning
S_OK | The method succeeded.
FWX_E_TERMINATING | The object is no longer valid.

See Also

FwxGetHostByAddrEvent, FwxGetHostByNameEvent


IFWXImpersonator

The impersonator object holds user information so that the Firewall service can impersonate the user.

Impersonators must be implemented as in-process servers.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IImpersonator Methods | Description
Impersonate | Impersonates the user's account.
RevertToSelf | Undoes impersonation.

Implementation

This interface is implemented by the Firewall service.

Remarks

Impersonators are typically implemented by the Firewall service, as in the case when the service is performing an access check.

Impersonators can also be implemented by filters that hold user credentials and are designed to function as application gateways. A filter implements IFWXImpersonator using IFWXSession::ImpersonateClient and IFWXSession::RevertToSelf.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXProxy::CreatePrivateSession


IFWXImpersonator::Impersonate Method

Impersonates an authenticated user.

HRESULT Impersonate()

Return Values

Value | Meaning
S_OK | Impersonation succeeded.
FWX_E_NOT_AUTHENTICATED | Cannot impersonate the user because the session is not authenticated.

See Also

IFWXSession::ImpersonateClient


IFWXImpersonator::RevertToSelf Method

Causes the Firewall service to revert to its own access level after a successful call to the Impersonate method.

HRESULT RevertToSelf()

See Also

IFWXSession::RevertToSelf


IFWXIOBuffer

The buffer object points to a reference-counted memory buffer, and provides means of managing the buffer.

The following rules apply to these buffers:

  • The allocator of a buffer owns the buffer. Only the allocator may alter the contents of the buffer. This means that the receiver must not modify a buffer received in the IFWXIOCompletion::CompleteAsyncIO method after a call to the IFWXSocket::Recv method with the IOBuffer parameter set to NULL.
  • A buffer that is sent (by way of the IFWXSocket::Send or IFWXSocket::SendTo method) must remain valid and unmodified until the reference count reaches zero. Even the owner of the buffer is not allowed to modify a buffer after it is sent.

The Send, SendTo, and Recv methods increment the reference count on the buffer. This reference is kept until CompleteAsyncIO returns. You must call Release for each AddRef that you called, and once more if you also created the buffer. Call AddRef if you keep a pointer to the buffer.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXIOBuffer Methods | Description
GetBufferAndSize | Gets the actual buffer and its size.
SetDataSize | Sets the actual size of the buffer that was used.
Append | Appends a specified number of bytes of data to the buffer object.
ReadAt | Reads a specified number of bytes starting at a specified offset from the beginning of the buffer.
SendToBuffer | Appends data from this buffer to another buffer.
GetBufferSizes | Gets the allocated and actual buffer sizes.

Remarks

This interface is generally implemented by the Firewall service. You may want to implement IFWXIOBuffer in your filter if:

  • You already have an allocated buffer that you want to send, and want to avoid creating a buffer copy. For example, the buffer was received from an RPC call or an API that cannot work with the Firewall service buffers.
  • You have to read into a pre-allocated buffer.
  • You want to use your own allocator for the buffer.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXIOBuffer::Append Method

Appends a specified number of bytes to the buffer object.

HRESULT Append(
  void const * pv,
  ULONG cb,
  ULONG * pcbWritten
);

Parameters

pv
[in] Pointer to the buffer which is appended to the buffer object.
cb
[in] The number of bytes of data to attempt to append to the buffer object.
pcbWritten
[out] Address of a ULONG variable where this method writes the actual number of bytes appended to the buffer object.

Return Values

Value | Meaning
S_OK | The data was successfully appended to the buffer object.
FWX_E_BUFFERFULL | Not all the data was appended to the buffer object because the buffer is full.

Remarks

This method does not resize the buffer. The pcbWritten parameter is valid even if an FWX_E_BUFFERFULL error is returned.


IFWXIOBuffer::GetBufferAndSize Method

Gets the actual data from the memory buffer.

HRESULT GetBufferAndSize(
  BYTE ** ppBuffer,
  DWORD * pdwSize
);

Parameters

ppBuffer
[out] Address of a variable that receives a pointer to the buffer.
pdwSize
[out] Pointer to DWORD data type that receives the size, in bytes, of the buffer.


IFWXIOBuffer::GetBufferSizes Method

Gets the allocated and actual buffer sizes.

HRESULT GetBufferSizes(
  LPDWORD pdwAlocatedSize,
  LPDWORD pdwActualSize
);

Parameters

pdwAlocatedSize
Pointer to variable that receives the allocated buffer size.
pdwActualSize
Pointer to variable that receives the actual buffer size.


IFWXIOBuffer::ReadAt Method

This method reads a specified number of bytes starting at a specified offset from the beginning of the buffer.

HRESULT ReadAt(
  ULONG ulOffset,
  void * pv,
  ULONG cb,
  ULONG * pcbRead
);

Parameters

ulOffset
Specifies the starting point from the beginning of the buffer for reading data.
pv
Pointer to the buffer into which the buffer content is copied.
cb
Specifies the number of bytes to attempt to read from the byte buffer.
pcbRead
Pointer to a location where this method writes the actual number of bytes copied from the buffer. You can set this pointer to NULL to indicate that you are not interested in this value. In this case, this method does not provide the actual number of bytes copied.


IFWXIOBuffer::SendToBuffer Method

Appends a specified number of bytes starting at a specified offset from the beginning of the buffer to the given destination buffer.

HRESULT SendToBuffer(
  IFWXIOBuffer * pDestinationBuffer,
  ULONG ulOffset,
  ULONG cb,
  ULONG * pcbCopied
);

Parameters

pDestinationBuffer
[in] Buffer to which data will be appended.
ulOffset
[in] Specifies the starting point from the beginning of the buffer for reading data.
cb
[in] Specifies the number of bytes to attempt to append to the destination buffer.
pcbCopied
[out] Address of a ULONG variable where this method writes the actual number of bytes appended to the buffer object.


IFWXIOBuffer::SetDataSize Method

Sets the actual size of the memory buffer that was used.

HRESULT SetDataSize(
  DWORD dwDataSize
);

Parameters

dwDataSize
[in] The actual size, in bytes, of the buffer that was used.

Return Values

Value | Meaning
S_OK | The data was successfully appended to the buffer object.
E_INVALIDARG | Requested size is larger than allocated size.

Remarks

When a buffer is used in a call to the IFWXSocket::Recv method, the SetDataSize method may be called if the size of available data is less than the size allocated for the buffer.

SetDataSize can be called by a filter after buffer content iss manipulated directly by means of IIOBuffer::GetBufferAndSize.

SetDataSize can be called by the proxy, when a buffer is passed to ISocket::Recv, in order to set the number of bytes actually received.


IFWXIOCompletion

IFWXIOCompletion is the application filter interface that receives notification from the Firewall service when an asynchronous I/O send, sendto, or receive operation is completed on an IFWXSocket interface.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXIOCompletion Methods | Description
CompleteAsyncIO | Receives notifications from the Firewall service when an asynchronous I/O operation completes.

Implementation

This interface is implemented by the application filter.

Remarks

All overlapped operations on an IFWXSocket interface require the filter to implement this interface. When calling a method that begins an overlapped operation, the filter must pass to that method a pointer to the IFWXIOCompletion interface. The Firewall service calls the IFWXIOCompletion interface of the filter when an overlapped operation completes.

ISA has two other notification methods for overlapped operations. The IFWXExternalIOCompletion::CompleteAsyncIO notification method is used for notification when a Win32 overlapped operation completes, and the IFWXAcceptCompletion::CompleteAsyncAccept method is used for notification when the IFWXNetworkSocket::Accept method completes.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXSocket::Recv, IFWXSocket::Send, IFWXSocket::SendTo


IFWXIOCompletion::CompleteAsyncIO Method

Receives notifications from the Firewall service when an asynchronous I/O operation completes. All overlapped operations on an IFWXSocket interface require the filter to implement this interface.

The CompleteAsyncIO method is where you should implement the logic of your filter, based on the protocol in which you are working.

HRESULT CompleteAsyncIO(
  BOOL fSuccess,
  DWORD Win32ErrorCode,
  IFWXIOBuffer * pIOBuffer,
  UserContextType UserData,
  LPSOCKADDR ExternalAddress,
  INT ExternalAddressLength
);

Parameters

fSuccess
[in] Success flag. If TRUE, the I/O operation succeeded. If FALSE, it failed.
Win32ErrorCode
[in] Win32 error code. This parameter is defined only if the fSuccess parameter is FALSE.
pIOBuffer
[in] Pointer to the IFWXIOBuffer interface for the data buffer, if this is a completion for a receive method.
UserData
[in] The UserData parameter that was passed to the I/O method.
ExternalAddress
[in] Pointer to a sockaddr structure that contains the address of the external source or external destination of a UDP packet. This parameter is passed only for the IFWXSocket::Recv method on a UDP socket. The ExternalAddress parameter is NULL for TCP sockets.

The address is the source when receiving from an external socket, and the target when receiving from an internal socket.

Note that IP packets on the Internet can be made to appear as though they are authorized when they are not. Therefore, do not rely on this address for authentication.

ExternalAddressLength
[in] Length, in bytes, of the ExternalAddress parameter.

Return Values

Value | Meaning
S_OK | The connection will be denied.

Any error should be handled in this method.

Remarks

Be aware that completion of a send or sendto operation indicates only that the next filter in the chain of filters received the buffer and began processing it. The buffer cannot be recycled at this point.

The UserData parameter provides a context to the notification. You can use the same notification interface for completion notifications from distinct network socket objects and differentiate between them using different values for UserData.

See Also

IFWXIOBuffer


IFWXNetworkSocket

The IFWXNetworkSocket interface is the Firewall service socket interface, and is derived from the IFWXSocket interface. The implementation uses the dynamic packet filter functionality of ISA Server to automatically open a port in the packet filter when necessary, and close it when the socket is closed. For more information see IP Packet Filtering.

Note

Before releasing this interface, you must call IFWXSocket::Close or IFWXSocket::Shutdown on it.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXSocket Methods | Description
Send | Sends a buffer asynchronously.
SendTo | Sends a buffer asynchronously to a specific address, on UDP sockets.
Recv | Receives a buffer asynchronously.
Shutdown | Shuts down the socket (half close).
Close | Closes the socket.

IFWXNetworkSocket Methods | Description
Connect | Establishes a connection to a specified socket. This method is similar to the Windows Sockets (Winsock) connect function, described in MSDN.
Bind | Associates a local address with a socket. This method is similar to the Winsock bind function, described in MSDN.
GetSockName | Gets the local name of a socket. This method is similar to the Winsock getsockname function, described in MSDN.
GetPeerName | Gets the remote name of a socket. This method is similar to the Winsock getpeername function, described in MSDN.
Listen | Listens on a TCP socket.
GetSockOpt | Gets a socket option. This method is similar to Winsock getsockopt function, described in MSDN.
SetSockOpt | Sets a socket option. This method is similar to the Winsock setsockopt function, described in MSDN.
Accept | Asynchronously permits a connection on a listening socket. This method is similar to the Winsock accept function, described in MSDN.
SetPacketFilterOptions | Sets options for the dynamic packet filtering used with this socket.

Remarks

A socket object that implements this interface can be created by using IFWXProxy::CreateNetworkSocket or IFWXSession::CreateNetworkSocket. The nature of the socket is determined by which of these two methods was used to create the object. A socket created using IFWXProxy::CreateNetworkSocket is not user specific. An example of a socket that should not be user specific is a listening socket. To create a user-specific socket, use IFWXSession::CreateNetworkSocket. For more information see Socket Implementation in ISA.

Implementation

This interface is implemented by the Firewall service.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXNetworkSocket::Accept Method

Asynchronously accepts a connection on a listening socket.

HRESULT Accept(
  IFWXAcceptCompletion * pIFWXAcceptCompletion,
  UserContextType UserData
);

Parameters

pIAcceptCompletion
[in] Pointer to the IFWXAcceptCompletion interface. This interface receives a notification when the call to the Accept method completes.
UserData
[in] An opaque value to pass to the IFWXAcceptCompletion::CompleteAsyncAccept notification method. This parameter provides a context to the notification.

Remarks

The UserData parameter provides a context to the notification. You can use the same notification interface for completion notifications from distinct network socket objects and differentiate between them using different values for UserData.

This method is similar to the Winsock accept function, which is described in MSDN.


IFWXNetworkSocket::Bind Method

Binds a socket to a specific address.

HRESULT Bind(
  LPSOCKADDR Address,
  INT AddressLength
);

Parameters

Address
[in] Pointer to a sockaddr structure that contains the address to assign to the socket.
AddressLength
[in] Length, in bytes, of the Address parameter.

Remarks

This method is similar to the Winsock bind function, which is described in MSDN.


IFWXNetworkSocket::Connect Method

Connects a socket to a specific address.

HRESULT Connect(
  LPSOCKADDR Address,
  DWORD AddressLength
);

Parameters

Address
[in] Pointer to a sockaddr structure that contains the address to connect to.
AddressLength
[in] Length, in bytes, of the Address parameter.

Remarks

This method is similar to the Winsock connect function, which is described in MSDN.


IFWXNetworkSocket::GetPeerName Method

Gets the remote address of a socket.

HRESULT GetPeerName(
  LPSOCKADDR Address,
  LPINT AddressLength
);

Parameters

Address
[out] Pointer to the address of a sockaddr structure that receives the address (name) of the peer.
AddressLength
[in, out] On input, specifies the size, in bytes, of the Address buffer. On output, receives the buffer size, in bytes, needed to hold the address.

Remarks

Used when a connection has been requested from outside the network, and you want to identify it. This method is similar to the Winsock getpeername function, which is described in MSDN.

Return Values

Value | Meaning
S_OK | The method succeeded.
HRESULT_FROM_WIN32(WSAEFAULT) | The name or the namelen parameter is not a valid part of the user address space, or the namelen parameter is too small.


IFWXNetworkSocket::GetSockName Method

Gets the local address of a socket.

HRESULT GetSockName(
  LPSOCKADDR Address,
  LPINT AddressLength
);

Parameters

Address
[out] Pointer to a Winsock sockaddr structure that receives the socket address (name).
AddressLength
[in, out] On input, specifies the size, in bytes, of the Address buffer. On output, receives the buffer size, in bytes, needed to hold the address.

Return Values

Value | Meaning
S_OK | The method succeeded.
HRESULT_FROM_WIN32(WSAEFAULT) | The name or the namelen parameter is not a valid part of the user address space, or the namelen parameter is too small.
HRESULT_FROM_WIN32(WSAEINVAL) | The socket has not been bound to an address with bind.

Remarks

This method is similar to the Winsock getsockname function, which is described in MSDN.


IFWXNetworkSocket::GetSockOpt Method

Gets a socket option.

HRESULT GetSockOpt(
  int level,
  int optname,
  char * optval,
  int optlen
);

Parameters

level
[in] Level at which the option is defined; the supported levels include SOL_SOCKET and IPPROTO_TCP.
optname
[in] Socket option for which the value is to be set.
optval
[in] A pointer to the buffer in which the value for the requested option is supplied.
optlen
[in, out] Size, in bytes, of the optval buffer.

Remarks

This method is similar to the Winsock getsockopt function, which is described in MSDN.


IFWXNetworkSocket::Listen Method

Listens on a TCP socket.

HRESULT Listen(
  INT Backlog
);

Parameters

Backlog
[in] Maximum length of the queue of pending connections. This is the same as the backlog parameter of the Winsock listen function, described in MSDN.

Remarks

The Listen method indicates to the network that you are willing to accept connections to the port for which you have a bind.


IFWXNetworkSocket::SetPacketFilterOptions Method

Sets options for dynamic packet filtering.

HRESULT SetPacketFilterOptions(
  BOOL fDiscardInbound,
  DWORD Reserved
);

Parameters

fDiscardInbound
[in] Discard-inbound flag. If TRUE, an opening in the packet filter is not created for inbound packets. If FALSE, an opening is created for inbound packets.
Reserved
Reserved for future use. This parameter must be zero.

Return Values

Value | Meaning
S_OK | The method succeeded.
E_INVALIDARG | Invalid parameter.
E_WSP_TERMINATING | The socket is already closed.

Remarks

This method can be called to restrict the opening of dynamic packet filters for use with this socket object. By default, the Firewall service creates a dynamic filter for communication through this socket. Use this method to avoid opening packet filters for this socket. For example, in order to limit a connection to internal clients, creation of openings in packet filters for incoming UDP datagrams or incoming TCP connections can be disabled using this method.


IFWXNetworkSocket::SetSockOpt Method

Sets a socket option.

HRESULT SetSockOpt(
  int level,
  int optname,
  char * optval,
  int optlen
);

Parameters

level
[in] Level at which the option is defined; the supported levels include SOL_SOCKET and IPPROTO_TCP.
optname
[in] Socket option for which the value is to be set.
optval
[in] A pointer to the buffer where the value for the requested option is supplied.
optlen
[in] Size, in bytes, of the optval buffer.

Remarks

This method is similar to the Winsock setsockopt function, which is described in MSDN.


IFWXOverlapped

The IFWXOverlapped interface is used to hook into the I/O completion port of the proxy, for asynchronous I/O with Win32 files. You can hook into the completion port thread pool by linking a handle to the completion port (call the IFWXProxy::HookToCompletionPort method). Overlapped Win32 functions must then be called with the Winsock structure OVERLAPPED returned by this interface.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXOverlapped Methods | Description
GetOverlapped | Gets a pointer to an overlapped structure.
SetNotificationInterface | Sets the callback for the completion of the overlapped I/O.

Implementation

This interface is implemented by the Firewall service.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXExternalIOCompletion


IFWXOverlapped::GetOverlapped Method

Gets a pointer to a Winsock OVERLAPPED structure to use with Win32 overlapped functions.

HRESULT GetOverlapped(
  LPOVERLAPPED * ppov
);

Parameters

ppov
[out] Pointer to a variable that receives a pointer to an OVERLAPPED structure.

Remarks

The handle used with the OVERLAPPED structure must first be hooked into the completion port of the Firewall service using the IFWXProxy::HookToCompletionPort method.


IFWXOverlapped::SetNotificationInterface Method

Sets the callback for the completion of the overlapped I/O.

HRESULT SetNotificationInterface(
  IFWXExternalIOCompletion * piExternalIOCompletion,
  UserContextType UserData
);

Parameters

piExternalIOCompletion
[in] Pointer to an IFWXExternalIOCompletion interface that is notified when the overlapped I/O is completed.
UserData
[in] An opaque value to pass to the IFWXExternalIOCompletion::CompleteAsyncIO notification method. This parameter provides a context to the notification.

Remarks

The UserData parameter provides a context to the notification. You can use the same notification interface for completion notifications from distinct network socket objects and differentiate between them using different values for UserData.


IFWXProxy

The IFWXProxy interface provides access to Firewall service functions for application filters that are not tied to any specific user session.

The Firewall service implements this interface and passes it to the IFWXFilter::FilterInit method.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXProxy Methods | Description
HookToCompletionPort | Associates a handle with the Firewall service completion port.
CreateOverlapped | Creates an overlapped object for use with handles associated with the completion port.
CreateNetworkSocket | Creates a socket object that works through the dynamic packet filter.
CreateConstBuffer | Creates a buffer object that wraps a user-supplied memory buffer.
CreateBuffer | Creates (allocates) a buffer object of the given size.
CreateWindowBuffer | Creates a buffer object that represents a window inside another buffer.
StartHeavyBlockingOperation | Notifies the Firewall service that a thread is busy with a lengthy blocking operation.
EndHeavyBlockingOperation | Notifies the Firewall service that a lengthy blocking operation has ended.
IsInternal | Checks if an address is internal (in the Local Address Table (LAT)).
GetNATSession | Gets a SecureNAT session object for a given client address.
DuplicateFilterHookEvents | Creates a duplicate of a given FwxFilterHookEvents structure.

Implementation

This interface is implemented by the Firewall service.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXFilter::FilterInit


IFWXProxy::CreateBuffer Method

Allocates a buffer object of the given size.

HRESULT CreateBuffer(
  DWORD dwBufferLength,
  IFWXIOBuffer ** pIOBuffer
);

Parameters

dwBufferLength
[in] Number of bytes to allocate.
pIOBuffer
[out] Address of a variable that receives a pointer to the IFWXIOBuffer interface.

Remarks

Use to create an empty buffer for data that is not constant. To create a buffer for data that is constant, use the IFWXProxy::CreateConstBuffer method.

Filters are not required to use this method. A filter may provide its own buffer objects as long as they support the IfWXIOBuffer interface.


IFWXProxy::CreateConstBuffer Method

Creates a buffer object that wraps the given data.

HRESULT CreateConstBuffer(
  BYTE * pBuffer,
  DWORD dwBufferLength,
  IFWXIOBuffer ** pIOBuffer
);

Parameters

pBuffer
[in] Pointer to the data buffer.
dwBufferLength
[in] Length, in bytes, of the buffer pointed to by pBuffer.
pIOBuffer
[out] Address of a variable that receives a pointer to the IFWXIOBuffer interface.

Remarks

Use only when the data is known to be a constant and the buffer memory does not have to be freed. To create a buffer for data that is not constant, use the IFWXProxy::CreateBuffer method.


IFWXProxy::CreateNetworkSocket Method

Creates a TCP/IP socket.

HRESULT CreateNetworkSocket(
  INT Protocol,
  IFWXNetworkSocket ** piSocket
);

Parameters

Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The method will create a TCP socket.
FWX_PROTOCOL_UDP | The method will create a UDP socket.

piSocket
[out] Address of a variable that receives a pointer to the IFWXNetworkSocket interface.

Remarks

Filters must use this interface and not call the Winsock dynamic-link library (DLL) directly to create a socket. The ISA socket object automatically opens packet filter ports required for any operation made with this socket. Sockets created with the Winsock DLL will not work with ISA's packet filtering.

A socket created by this method is not associated with a specific user. To create a socket that is user specific, use the IFWXSession::CreateNetworkSocket method.


IFWXProxy::CreateOverlapped Method

Creates an overlapped object that supports the IFWXOverlapped interface for use with handles hooked to the completion port with the HookToCompletionPort method.

HRESULT CreateOverlapped(
  IFWXOverlapped ** ppOverlapped
);

Parameters

ppOverlapped
[out] Address of a variable that receives a pointer to the IFWXOverlapped interface.

See Also

IFWXExternalIOCompletion


IFWXProxy::CreatePrivateSession Method

Creates a private session object for a given client.

HRESULT CreatePrivateSession(
  LPSOCKADDR ClientAddress,
  DWORD ClientAddressLength,
  LPSOCKADDR ProxyInternalAddress,
  DWORD ProxyInternalAddressLength,
  IFWXImpersonator *Impersonator,
  IFWXSession ** ppPrivateSession
);

Parameters

ClientAddress
[in] Pointer to a sockaddr structure that contains the address of the client for which the session object is needed.
ClientAddressLength
[in] Length, in bytes, of the structure pointed to by the ClientAddress parameter.
ProxyInternalAddress
[in] Pointer to a sockaddr structure that contains the internal address of the proxy used to communicate with the client.
ProxyInternalAddressLength
[in] Length, in bytes, of the structure pointed to by the ProxyInternalAddress parameter.
Impersonator
[in] Pointer to impersonator object that will be used for impersonating the session's user. This parameter can be NULL, in which case only the client IP address will be used when processing rules.
ppPrivateSession
[out] Address of a variable that receives a pointer to the IFWXSession interface on the newly created session.

Remarks

Session objects are created automatically for Firewall service or SecureNAT client requests, but not when an application connects to the proxy. A filter that acts as an application level proxy, may have to create a private session object using this method in order to have access to session-dependent functions.

A private session object allows a filter to use an application-level authentication scheme.


IFWXProxy::CreateWindowBuffer Method

Creates a buffer object that represents a window inside another buffer.

HRESULT CreateWindowBuffer(
  IFWXIOBuffer * pIOBufferOriginal,
  DWORD dwOffset,
  DWORD dwLength,
  IFWXIOBuffer ** pIOBuffer
);

Parameters

pIOBufferOriginal
[in] Pointer to the IFWXIOBuffer interface on the buffer object from which the window should be taken.
dwOffset
[in] Offset in the original buffer of the beginning of the window.
dwLength
[in] Length, in bytes, of the window.
pIOBuffer
[out] Address of a variable that receives a pointer to the IFWXIOBuffer interface.

Remarks

This method allows you to point to a portion of a buffer, so that a portion of it can be sent.


IFWXProxy::DuplicateFilterHookEvents Method

Creates a duplicate of the given FwxFilterHookEvents structure in a buffer allocated using the COM function CoTaskMemAlloc. This buffer can be returned by the IFWXFilter::FilterInit and IFWXFilter::AttachToSession methods.

HRESULT DuplicateFilterHookEvents(
  FilterHookEvents * pEventsToDuplicate,
  FilterHookEvents ** ppCopy
);

Parameters

pEventsToDuplicate
[in] Pointer to the FilterHookEvents structure to copy.
ppCopy
[out] Pointer to a buffer that receives the new FilterHookEvents structure.


IFWXProxy::EndHeavyBlockingOperation Method

Marks the end of a blocking operation. For more information, see StartHeavyBlockingOperation.

HRESULT EndHeavyBlockingOperation()

Return Values

Value | Meaning
S_OK | Method succeeded.
FWX_E_NOT_IN_BLOCKING_OP | There is no blocking operation to end.


IFWXProxy::GetNATSession Method

Gets, or if necessary, creates a SecureNAT session object for a given client.

HRESULT GetNATSession(
  LPSOCKADDR Address,
  DWORD AddressLength,
  IFWXSession ** ppiPNATSession
);

Parameters

Address
[in] Pointer to a sockaddr structure that contains the address of the SecureNAT client for which the session object is needed. The port is ignored.
AddressLength
[in] Length, in bytes, of the structure pointed to by the Address parameter.
ppiPNATSession
[out] Address of a variable that receives a pointer to the IFWXSession interface on the SecureNAT session object for the given address.

Remarks

This method could be used to direct a primary inbound connection to a particular SecureNAT client. Alternatively, the connection could be directed using IFWXProxy::CreatePrivateSession.


IFWXProxy::HookToCompletionPort Method

Associates a handle with the Firewall service completion port. The caller must use overlapped structures that are provided by the Firewall service using the IFWXOverlapped interface. Overlapped objects are obtained by calling the CreateOverlapped method.

HRESULT HookToCompletionPort(
  DWORD h
);

Parameters

h
[in] Win32 handle that should be associated with the Firewall service completion port.

See Also

IFWXExternalIOCompletion


IFWXProxy::IsInternal Method

Checks whether the given address is in the Local Address Table (LAT).

HRESULT IsInternal(
  LPSOCKADDR Address,
  INT AddressLength
);

Parameters

Address
[in] Pointer to a sockaddr structure that contains the address to be checked.
AddressLength
[in] Length, in bytes, of the address specified in the Address parameter.

Return Values

Value | Meaning
S_OK | The address is in the LAT (internal).
S_FALSE | The address is not in the LAT (external).
Error code | The address is invalid or not an IP address.


IFWXProxy::StartHeavyBlockingOperation Method

Notifies the Firewall service that a thread is busy with a lengthy blocking operation.

HRESULT StartHeavyBlockingOperation()

Return Values

Value | Meaning
S_OK | Method succeeded.
FWX_E_ALREADY_IN_BLOCKING_OP | The blocking operation is already started.

Remarks

The StartHeavyBlockingOperation and EndHeavyBlockingOperation methods manage the creation of additional completion-port worker threads when all existing threads are blocked. The completion port model works best when all I/O operations are overlapped. When some calls are blocking, all worker threads may be blocked, and the service will be idle. When this method is used the Firewall service keeps track of the number of threads that are busy with blocking operations, and creates new threads when necessary.

Call the StartHeavyBlockingOperation method before making a blocking operation such as a call to the gethostbyname function, or reading (non-overlapped) from a file or a pipe. Call EndHeavyBlockingOperation after the blocking call returns.

Do not call StartHeavyBlockingOperation before waiting for a critical section or a resource on which other threads are likely to be blocked. If the newly created thread is blocked on the same critical section, there will be greater congestion on the critical section and more context switches, resulting in an overall reduction in performance.


IFWXProxyAction

The IFWXProxyAction interface cancels a proxy action.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXProxyAction Methods | Description
Cancel | Cancels the action.

Implementation

This interface is implemented by the Firewall service.

Remarks

A filter may request that the Firewall service perform a proxy action, such as connecting to a certain target, based on a proxy event or address. A proxy action is always requested in anticipation of an event that may not occur. This interface permits cancellation of the Firewall service action request. Typically, a proxy action relates only to events for which a filter is not registered.

For example, if the action is the future establishment of a secondary connection, IFWXProxyAction can be used to cancel the action if the primary connection is terminated.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXProxyAction::Cancel Method

Cancels a Firewall service (proxy) action.

HRESULT Cancel()

Return Values

Value | Meaning
S_OK | The method succeeded.
E_WSP_TERMINATING | The action has already been cancelled.

Remarks

The Firewall service can automatically cancel certain actions, including:

  • Actions that are supposed to happen only once (the action is canceled after its first occurrence).
  • Actions that have a timeout.
  • An action associated with a session that has been killed.

See Also

IFWXSession::AllowFutureConnect, IFWXSession::SetDataFilterFactory


IFWXSession

The Firewall service implements the IFWXSession interface on the session object.

The session object implements session-specific functions that impersonate the user account, test access-control lists (ACLs) against the session user, get information about the client computer, and perform protocol operations.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXSession Methods | Description
GetClientAddress | Returns the address of the user.
GetClientMachineName | Returns the name of the user's computer.
ImpersonateClient | Impersonates the user's account.
RevertToSelf | Undoes impersonation.
AccessCheck | Checks the user's permission against the ACL of a filter installed protocol.
HostAccessCheck | Checks the user's permission to access a specified host.
AllowFutureConnect | Prepares for a secondary connection by a client.
BindForClient | Prepares for an inbound secondary connection for a Firewall service or SecureNAT client. Makes a bind on behalf of a client.
EmulateClientBind | Prepares for a primary inbound connection to a Secure NAT client.
GetSessionFlags | Gets the state of the session.
RedirectConnections | Redirects an internal firewall service interface connection to a given address.
AttachFilter | Causes a filter to be attached to the session.
SetDataFilterFactory | Sets a data filter class factory for an event.
RetroactiveAllowBind | Allows inbound connections or packets for a bind operation that already took place.
EnableInternalAddressTranslation | Enables or disables address translation for inbound connections.
CreateNetworkSocket | Creates a TCP/IP socket that is associated with this session.

Implementation

This interface is implemented by the Firewall service.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXSession::AccessCheck Method

Checks the permission of the session user to use a protocol that was previously registered by calling the IFWXFilterAdmin::RegisterProtocolForFilter method.

HRESULT AccessCheck(
  REFGUID ProtocolGuid
);

Parameters

ProtocolGuid
[in] GUID identifying the protocol to check.

Return Values

Value | Meaning
S_OK | The user is in the ACL; that is, the user has permission.
S_FALSE | The user is not in the ACL; that is, the user was denied access.
Error code | The method failed.

Remarks

Though you would typically use this method to check a user's permission to use a protocol that was registered by calling IFWXFilterAdmin::RegisterProtocolForFilter, AccessCheck Method can be used to check a user's access to any protocol.


IFWXSession::AllowFutureConnect Method

Allows a client to make secondary outbound connections.

HRESULT AllowFutureConnect(
  LPSOCKADDR Address,
  DWORD AddressLength,
  LPSOCKADDR ProxyExternalAddress,
  DWORD ProxyExternalAddressLength,
  INT Protocol,
  DWORD dwFlags,
  REFGUID ProtocolGuid,
  IFWXSessionFilter *pSessionFilter,
  IUnknown *punkContext,
  IFWXProxyAction ** ppProxyAction
);

Parameters

Address
[in] Pointer to a sockaddr structure that contains the address to which the client will connect.
AddressLength
[in] Length, in bytes, of the structure pointed to by the Address parameter.
ProxyExternalAddress
[in] Pointer to a sockaddr structure that contains the proxy external address used for the connection. This is useful in the case of multi-homed proxy servers. Requesting a specific address ensures that a secondary connection uses the same proxy IP address as the primary. This parameter can be NULL, defaulting to INADDR_ANY and 0 (any port).
ProxyExternalAddressLength
[in] Length, in bytes, of the ProxyExternalAddress structure.
Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The connection will use the TCP protocol.
FWX_PROTOCOL_UDP | The connection will use the UDP protocol.
dwFlags
[in] Connection flags. This parameter can be a combination of the following connection flags:
Value | Description
FWX_FLAG_ADDRESS_BASED | The permission should be associated with the client address, not the client session. This is necessary if the protocol involves connections that are intiated by different processes.
FWX_FLAG_ALLOW_MULTIPLE | By default, a single outbound connection is expected. If this flag is specified, multiple connections to the same address will be possible.
FWX_FLAG_TIMEOUT | The client is expected to use the permission within approximately one minute of the call. If the client does not make the connection, the permission automatically expires.
FWX_FLAG_NO_KERNEL_MODE | The connection is forced to go through user-mode code, even if currently there seems to be no reason not to use kernel-mode for the connection.

ProtocolGuid
[in] GUID identifying the protocol that the connection is part of. The GUID is the same GUID supplied to IFWXFilterAdmin::RegisterProtocolForFilter.
*pSessionFilter
[in] Pointer to the IFWXSessionFilter object. Use with the UserContext parameter to receive the fwx_EstablishedConnection event from the proxy.
*punkContext
[in] Provides user context information regarding the connection. Use with the *pSessionFilter parameter to receive the fwx_EstablishedConnection event from the proxy.
ppProxyAction
[out] Address of a variable that receivespointer to the IFWXProxyAction interface on the proxy action object created as a result of this call.

Remarks

A filter should call this method when it detects, by inspecting another (usually the "primary") connection, that the client needs to make a TCP connection to the server, or to send one or more UDP datagrams to that server. This is usually known when the server sends an address to the client. For example, when an FTP server sends the following:

227 Entering Passive Mode (198,105,232,1,4,22)

it is instructing the client to connect to address 198.105.232.1 on port 1046.

The call allows an outbound connection from the client denoted by the session object (the IP address given by the GetClientAddress method) to the requested address.

Using this method is preferable to defining a secondary port, or port range in a protocol definition, and to handling all connect events and calling IFWXConnection::SetProtocol or IFWXConnection::Deny, as appropriate.

It is impossible to attach a data filter to a kernel-mode connection. For this reason, the Firewall service will not make a kernel-mode connection if a data filter is expected to be set on the connection, or if a filter is registered for the resulting connection event. When a filter calls SetDataFilterFactory, the decision has already been made, and cannot be modified. A filter that is going to call SetDataFilterFactory for the resulting connection should specify FWX_FLAG_NO_KERNEL_MODE. A filter that already called SetDataFilterFactory for the resulting connection is not required to specify this flag.

The FWX_FLAG_TIMEOUT flag cannot be specified in conjunction with the FWX_FLAG_ALLOW_MULTIPLE flag.

See Also

IFWXConnection::SetProtocol, IFWXProxyAction, IFWXSession::GetClientAddress, IFWXSession::SetDataFilterFactory, IFWXFilterAdmin::RegisterProtocolForFilter


IFWXSession::AttachFilter Method

Causes a filter to be loaded for this session even if the initial event for this filter did not yet happen. If the filter has already attached a session filter for this session, nothing happens; otherwise, the filter's IFWXFilter::AttachToSession method is called.

HRESULT AttachFilter(
  REFCLSID guidFilter
);

Parameters

guidFilter
[in] CLSID of the filter to load.


IFWXSession::BindForClient Method

Bind on the Firewall service on behalf of the client.

The BindForClient method permits a SecureNAT client to receive a secondary inbound connection. It also allows a client application — for which the Firewall client component failed to create a remote socket for a bind call — to receive an inbound connection. The processing done by the filter can be the same in both cases. The only difference is that in the case of a SecureNAT client, the filter knows that the client is sending a private address that has to be translated. For a Firewall client, the filter has to verify that the client is sending an internal address on an external interface.

HRESULT BindForClient(
  LPSOCKADDR ClientAddresses[],
  DWORD ClientAddressLength,
  LPSOCKADDR ProxyAddress,
  DWORD ProxyAddressLength,
  INT Protocol,
  DWORD dwNumberOfAddresses,
  DWORD dwFlags,
  REFGUID ProtocolGuid,
  IFWXSessionFilter *pSessionFilter,
  UserContextType UserContext,
  PFWXICONNECTION ConnectionArray[]
);

Parameters

ClientAddresses[]
[in] Pointer to an array of pointers to sockaddr structures that contain the addresses that the client used. The array contains dwNumberOfAddresses pointers. In rare cases, a client address is not yet known. In these cases, it is possible to specify an address of all zeros. Once the client address is known, call the IFWXConnection::SetClientAddress method.
ClientAddressLength
[in] Length, in bytes, of the addresses pointed to by the ClientAddresses parameter.
ProxyAddress
[in, out] Pointer to a sockaddr structure that contains the address to which the filter is to bind. This is usually an external IP address of the proxy, and PORT_ANY. On return, this parameter receives the actual address to which the filter binds.
ProxyAddressLength
[in] Length, in bytes, of the ProxyAddress parameter.
Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The request is for a TCP socket.
FWX_PROTOCOL_UDP | The request is for a UDP socket.
dwNumberOfAddresses
[in] Number of consecutive addresses to assign.
dwFlags
Connection flags. This parameter can be any combination of the following flag values:
Value | Description
FWX_FLAG_ALLOW_MULTIPLE | By default, only a single connection is expected on a listening TCP socket (for example, FTP). If more than one connection to the same address and port is expected, specify this flag. For UDP sockets, set the flag if datagrams are expected from more than one source. If only a single source will send datagrams, do not set this flag.
FWX_FLAG_TIMEOUT | When this flag is set, UDP connections are closed automatically when they are detected to be idle. For TCP, when no connection is accepted within the timeout period of approximately one minute, the listening connection is closed. When not set, the calling filter must call the IFWXConnection::Kill method to terminate the connection.
FWX_FLAG_NO_KERNEL_MODE | The connection is forced to go through user-mode code, even if currently there seems to be no reason not to use kernel-mode for the connection.

ProtocolGuid
[in] GUID identifying the protocol that the connection is part of. The GUID is the same GUID supplied to IFWXFilterAdmin::RegisterProtocolForFilter.
*pSessionFilter
[in] Pointer to the IFWXSessionFilter object. Use with the UserContext parameter to receive the fwx_EstablishedConnection event from the proxy. This parameter can be NULL, in which case no notification will be provided.
UserContext
[in] Provides user context information regarding the connection. Use with the *pSessionFilter parameter to receive the fwx_EstablishedConnection event from the proxy. This parameter can be NULL.
ConnectionArray[]
[out] Pointer to an array of dwNumberOfAddresses IFWXConnection interface pointers. The array is filled with pointers to the IFWXConnection interfaces on the resulting connection objects. The array contains dwNumberOfAddresses pointers.

Remarks

This method should be called by a filter that enables a specific protocol when upon detecting, by inspecting the primary connection, that the client is expecting a secondary inbound connection (either TCP or UDP). This is usually known when the client sends its address to the server as part of the protocol. For example, when an FTP client sends the following:

PORT 10,0,0,8,6,17

it is instructing the server to connect to the address 10.0.0.8 on port 1553.

A Secure NAT editor detecting such a command should call the BindForClient method, which binds an external socket and associates it with the client socket.

The call allows inbound connections to the client denoted by the session object. The ClientAddress parameter will be the address and port sent by the client, and will usually have the same IP address as that given by the GetClientAddress method.

Like other bind requests, any filter registered for the pe_Bind_* events is notified about this bind and has an opportunity to deny it. The filter may also install a data filter, or even emulate the bind.

If no data filter is installed, the Firewall service handles this connection in kernel mode. A connection handled in kernel mode is less delayed and uses fewer CPU and memory resources on the proxy.

The filter is expected to modify the control stream and send a modified address to the server. For the FTP example, the PORT command will be modified to reflect the address and port returned in the ProxyAddress parameter.

This method also allows multiple consecutive ports to be assigned, and returns connection objects that can be used to control the resulting connections.

When dwNumberOfAddresses is greater than 1, a set of consecutive ports is allocated. The lowest port allocated is a multiple of dwNumberOfAddresses. The set of addresses specified in ConnectionArray does not have to be consecutive. The first address in ConnectionArray corresponds to the lowest port, the second to the next port, and so forth.

On input, the ProxyAddress parameter can be used to force binding to a specific interface of the proxy, and to force a specific port (only when dwNumberOfAddresses is 1). On output, the ProxyAddress is filled with the bound proxy address. When dwNumberOfAddresses is greater than 1, the address with the lower port number is returned.

If FWX_FLAG_TIMEOUT is not specified, the connection object will not be deleted until the filter calls the IFWXConnection::Kill method.

The FWX_FLAG_TIMEOUT flag cannot be specified in conjunction with the FWX_FLAG_ALLOW_MULTIPLE flag.

It is impossible to attach a data filter to a kernel-mode connection. For this reason, the Firewall service will not make a kernel-mode connection if a data filter is expected to be set on the connection, or if a filter is registered for the resulting connection event. When a filter calls SetDataFilterFactory, the decision has already been taken, and cannot be modified. A filter that is going to call SetDataFilterFactory for the resulting connection should specify FWX_FLAG_NO_KERNEL_MODE. A filter that already called SetDataFilterFactory for the resulting connection is not required to specify this flag.

See Also

IFWXConnection, IFWXConnection::Kill, IFWXSession::BindForClient, IFWXConnection::SetClientAddress, IFWXSession::SetDataFilterFactory, IFWXFilterAdmin::RegisterProtocolForFilter


IFWXSession::CreateNetworkSocket Method

Creates a TCP/IP socket that is associated with this session.

HRESULT CreateNetworkSocket(
  INT Protocol,
  IFWXNetworkSocket ** piSocket
);

Parameters

Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The method will create a TCP socket.
FWX_PROTOCOL_UDP | The method will create a UDP socket.

piSocket
[out] Address of a variable that receives a pointer to the IFWXNetworkSocket interface.

Return Values

Value | Meaning
S_OK | The socket was created.
E_OUTOFMEMORY | Insufficient memory or resources to process the event; the socket was not created.
HRESULT_FROM_WIN32(win32 error code) | Winsock or Win32 error code. The method failed.

Remarks

The socket created by this method is user-specific, and its activity obeys the policy rules for the session. Connections are logged as if they were performed by the session's user.

To create a socket that is not user specific, use IFWXProxy::CreateNetworkSocket.


IFWXSession::EmulateClientBind Method

Allows a client that did not create a remote bind to receive a primary inbound connection.

HRESULT EmulateClientBind(
  LPSOCKADDR ClientAddress,
  DWORD ClientAddressLength,
  LPSOCKADDR ProxyAddress,
  DWORD ProxyAddressLength,
  INT Protocol,
  REFGUID ProtocolGuid,
  IFWXConnection ** piConnection
);

Parameters

ClientAddress
[in] Pointer to a sockaddr structure that contains the address that the client used.
ClientAddressLength
[in] Length, in bytes, of the ClientAddress parameter.
ProxyAddress
[in] Pointer to a sockaddr structure that contains the address to which the filter is emulating bind. This is usually an external IP address of the Firewall service and a specific port number. The EmulateClientBind method does not really bind to that address. The address is used for the bind event generated.
ProxyAddressLength
[in] Length, in bytes, of the ProxyAddress parameter.
Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The request is for a TCP socket.
FWX_PROTOCOL_UDP | The request is for a UDP socket.

ProtocolGuid
[in] GUID identifying the protocol that the connection is part of. The GUID is the same GUID supplied to IFWXFilterAdmin::RegisterProtocolForFilter.
piConnection
[out] Pointer to a buffer that receives the address of the resulting connection object.

Remarks

This method should be called by a filter whose purpose is to enable a specific protocol. The filter uses this method when it needs to forward a primary connection made from an external source to a local computer that did not make a remote bind through the Firewall service. For example, this could be a local computer that is not a Firewall client.

This method will usually be called by a filter that is listening on some well-known port when it receives a connection. The filter decides (based on the source address, data exchange with the caller, a hard-coded address, and so on) that this call should be forwarded to some internal client.

The filter cannot use the BindForClient method because the well-known port is already in use and the connection was already made.

This method creates a connection object on which the caller can call the IFWXConnection::EmulateConnection method and forward the connection to the client.

Like other bind requests, any filter registered for the pe_Bind_* events is notified about this bind and has an opportunity to deny it. It may also install a data filter. Other filters cannot emulate this bind because the caller is already emulating it.

See Also

IFWXConnection::EmulateConnection, IFWXSession::BindForClient, IFWXFilterAdmin::RegisterProtocolForFilter


IFWXSession::EnableInternalAddressTranslation Method

Enables or disables internal address translation.

HRESULT EnableInternalAddressTranslation(
  BOOL fEnable
);

Parameters

fEnable
[in] A nonzero value enables translation of external addresses to internal addresses. Zero disables the translation.

Return Values

Value | Meaning
S_OK | The method succeeded.
WFX_E_NOT_SUPPORTED | Modifying this property is not allowed for this session.

Remarks

By default, when a filter calls BindForClient, the address of the external host connecting will be seen by the internal client. In some circumstances this is not desirable. When internal address translation is enabled, the internal address of the Firewall service will be used instead.

See Also

IFWXSession::BindForClient


IFWXSession::GetClientAddress Method

Gets the address of the user.

HRESULT GetClientAddress(
  LPSOCKADDR Address,
  LPDWORD AddressLength
);

Parameters

Address
[out] Pointer to a sockaddr structure that receives the client address (port = 0 for AF_INET.
AddressLength
[in, out] Pointer to the length, in bytes, of the address specified in the Address parameter. On return, AddressLength receives the actual size of the address returned in Address.


IFWXSession::GetClientMachineName Method

Gets the name of the client machine, if it is available. The Firewall client DLL passes the machine name in the request. The name is not available for SecureNAT clients.

HRESULT GetClientMachineName(
  LPSTR * pszMachineName
);

Parameters

pszMachineName
[out] Address of a buffer that receives a pointer to the requested computer name string. The caller must free the pszMachineName buffer using the CoTaskMemFree function.


IFWXSession::GetSessionFlags Method

Gets flags that provide information about the session.

HRESULT GetSessionFlags(
  LPDWORD pOutputFlags
);

Parameters

pOutputFlags
[out] Pointer to variable that receives the session flags. The flags can be a combination of the following values:
Value | Description
FWX_SESSION_NAT | The session is using SecureNAT (not a Firewall service control channel).
FWX_SESSION_PRIVATE | The session was created by a filter using IFWXProxy::CreatePrivateSession.
FWX_SESSION_AUTHENTICATED | The Firewall service authenticated the session.
FWX_SESSION_TERMINATED | The session was terminated and is no longer valid.

See Also

IFWXProxy::CreatePrivateSession


IFWXSession::HostAccessCheck Method

Using the Site and Content Rules, this method checks the permission of the session user to access a specified host.

HRESULT HostAccessCheck(
  LPHOSTENT Hostent,
  LPCSTR pszPath,
  LPCSTR pszMime,
  DWORD dwFlags
);

Parameters

Hostent
[in] Pointer to a buffer containing a hostent structure to be checked.
pszPath
[in] Pointer to the path to be checked. This parameter may be NULL if path is unknown or irrelevant.
PszMime
[in] Pointer to string containing the MIME data type (such as "text/html") to be checked. This parameter can be NULL if the MIME type is unknown or irrelevant.
dwFlags
[in] Optional. HostAccessCheck flags. This parameter can be a combination of the following values, or 0 if neither of the options apply:
Value | Description
FWX_FLAG_FWX_FLAG_USE_MIME_MULTIPLE | The pszMime parameter is currently NULL, but may be known later. If this flag is specified, and the pszMime parameter is NULL and the MIME type is required for processing of the rules, FWX_E_MIME_NEEDED will be returned.
FWX_FLAG_USE_EXTENTION | Use the extension of the pszPath parameters for content filtering.

Return Values

Value | Meaning
S_OK | The user allowed to access the host.
S_FALSE | The user is denied access to the host.
FWX_E_MIME_NEEDED | The MIME type is required.
Error code | The method failed.

Remarks

The hostent structure may contain names or addresses, or both names and addresses. Access is checked based on the information available in the hostent structure.


IFWXSession::ImpersonateClient Method

Calls IFWXImpersonator::Impersonate so that a filter can impersonate the authenticated user for this session.

HRESULT ImpersonateClient()

Remarks

This function will fail if the current session user is not authenticated. This could be either because the session belongs to a SecureNAT client, or because the Firewall service currently does not require authentication.

This method is used specifically by filters. Impersonation by the Firewall service is through the IFWXImpersonator interface.

See Also

RevertToSelf


IFWXSession::RedirectConnections Method

Enables connections using a local, internal proxy address.

HRESULT RedirectConnections(
  LPSOCKADDR ConnectAddresses[],
  DWORD ConnectAddressLength,
  DWORD dwNumberOfAddresses,
  LPSOCKADDR InternalAddress,
  LPDWORD InternalAddressLength,
  LPSOCKADDR ProxyExternalAddress,
  DWORD ProxyExternalAddressLength,
  INT Protocol,
  DWORD dwFlags,
  REFGUID ProtocolGuid,
  IFWXSessionFilter *pSessionFilter,
  UserContextType UserContext,
  PIFWXPROXYACTION ProxyActionArray[]
);

Parameters

ConnectAddresses[]
[in] Pointer to an array of pointers to sockaddr structures that contain the addresses to which the client connections will be redirected.
ConnectAddressLength
[in] Length, in bytes, of the addresses pointed to by the ConnectAddresses parameter.
dwNumberOfAddresses
[in] Number of addresses in the ConnectAddresses array.
InternalAddress
[in] Pointer to a sockaddr structure that contains the address to which the client should connect instead of ConnectAddresses. This would be an internal IP address of the proxy.

When dwNumberOfAddresses is more than one, consecutive ports will be allocated by the Firewall service and this parameter will contain the address using the lowest port.

InternalAddressLength
[in, out] Length, in bytes, of the InternalAddress parameter.
ProxyExternalAddress
[in] Pointer to a sockaddr structure that contains the proxy external address used for the connection. This is useful in the case of multi-homed proxy servers. Requesting a specific address ensures that a secondary connection uses the same proxy IP address as the primary. This parameter can be NULL, defaulting to INADDR_ANY and 0 (any port).
ProxyExternalAddressLength
[in] Length, in bytes, of the ProxyExternalAddress structure.
Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The connection will use a TCP socket.
FWX_PROTOCOL_UDP | The connection will use a UDP socket.

dwFlags
[in] Connection flags. This parameter can be a combination of the following values:
Value | Description
FWX_FLAG_ALLOW_MULTIPLE | By default, a single outbound connection is expected. If this flag is specified, multiple connections to the same address will be possible.
FWX_FLAG_TIMEOUT | The client is expected to use the permission shortly after the call. If the client does not make the connection, the permission automatically expires.
FWX_FLAG_NO_KERNEL_MODE | The connection is forced to go through user-mode code, even if currently there seems to be no reason not to use kernel mode for the connection.

ProtocolGuid
[in] GUID that identifies the protocol that the connection is part of. The GUID is the same GUID supplied to IFWXFilterAdmin::RegisterProtocolForFilter.
*pSessionFilter
[in] Pointer to the IFWXSessionFilter object. Use with the UserContext parameter to receive the fwx_EstablishedConnection event from the proxy.
UserContext
[in] Provides user context information regarding the connection. Use with the *pSessionFilter parameter to receive the fwx_EstablishedConnection event from the proxy.
ProxyActionArray[]
[out] Pointer to an array of IFWXProxyAction interface pointers. The array is filled with pointers to IFWXProxyAction interfaces to the proxy action objects created by this call. The array contains dwNumberOfAddresses pointers.

Remarks

This method is intended for use by filters that act as an application proxy that has to establish secondary connections, and has to give the same address as the primary connection for the secondary connection.

Filters for Firewall clients and for SecureNAT clients usually use AllowFutureConnect instead.

Calling this method causes all filters that are registered for connect events on the appropriate port to be notified. If no data filters are installed, a kernel-mode NAT redirection may result.

See Also

IFWXProxyAction, IFWXSession::AllowFutureConnect, IFWXFilterAdmin::RegisterProtocolForFilter


IFWXSession::RetroactiveAllowBind Method

Allows a Firewall client to receive a secondary inbound connection on a socket that was previously bound by the Firewall client, but was not necessarily approved by the proxy.

HRESULT RetroactiveAllowBind(
  INT Protocol,
  LPSOCKADDR Address,
  DWORD AddressLength,
  REFGUID ProtocolGuid
);

Parameters

Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The bind uses the TCP protocol.
FWX_PROTOCOL_UDP | The bind uses the UDP protocol.

Address
[in] Pointer to a sockaddr structure that contains the Firewall service external address for which this request is made. The address can be INADDR_ANY. The port number must be nonzero.
AddressLength
[in] Length, in bytes, of the structure pointed to by the Address parameter.
ProtocolGuid
[in] GUID that identifies the protocol of which the connection is part. The GUID is the same GUID supplied to IFWXFilterAdmin::RegisterProtocolForFilter.

Return Values

Value | Meaning
S_OK | The method succeeded.
S_FALSE | The connection exists and was already allowed.
E_INVALIDARG | Invalid parameter.
HRESULT_FROM_WIN32(ERROR_NOT_FOUND) | No connection with the specified address was found.
FWX_E_TERMINATING | The (bind) connection exists, but is already terminating.
FWX_E_PROTOCOL_RULES_DENIED | The protocol rules do not allow the user to use the protocol specified by the ProtocolGuid parameter.

Remarks

Usually a filter will know that a bind call made by a Firewall client is valid only after the bind call succeeds and the Firewall client sends the address to its peer. For this reason, the Firewall service will not fail a bind call even when the service does not allow the client inbound access. Instead, the Firewall service marks the connection and discards datagrams sent, or connection attempts to that address, unless the bind becomes valid later.

When packet filtering is enabled, an opening in the dynamic packet filter will only be created for allowed connections.


IFWXSession::RevertToSelf Method

Calls IFWXImpersonator::RevertToSelf. Reverts to self after a successful call by the filter to the IFWXSession::ImpersonateClient method to impersonate the authenticated user.

HRESULT RevertToSelf()

Remarks

This method is used specifically by filters. Impersonation by the Firewall service is through the IFWXImpersonator interface.


IFWXSession::SetDataFilterFactory Method

Allows a filter to set a data filter factory for events for which the filter is not registered. This method can be used to reduce the number of events for which a filter registers.

HRESULT SetDataFilterFactory(
  ProxyEventType eProxyEvent,
  LPSOCKADDR Address,
  DWORD AddressLength,
  IClassFactory * pIClassFactory,
  IUnknown * punkFilterContext,
  DataFilterPriorityClass PriorityClass,
  DWORD dwFlags,
  IFWXProxyAction ** ppProxyAction
);

Parameters

eProxyEvent
[in] Type of event for which a data filter is requested. This can be one of the following values from the FwxProxyEventType enumeration:

fwx_Connect_Tcp
fwx_Bind_Udp
fwx_AcceptedConnection
fwx_Udp_Destination

Address
[in] Pointer to a sockaddr structure that contains the address and port for events which should cause a data filter to be instantiated and attached. If eProxyEvent is pe_Connect_Tcp or pe_Udp_Destination, the address is the remote address. If eProxyEvent is pe_Bind_Udp or pe_AcceptedConnection, the address is the bind address. The address must be of type AF_INET, and can be either a specific IP address or INADDR_ANY.
AddressLength
[in] Length, in bytes, of the structure pointed to by the Address parameter.
pIClassFactory
[in] Pointer to a class factory for objects that support the IFWXDataFilter interface.
punkFilterContext
[in] Pointer to an optional interface that can be used to pass context information to the data filter. This interface will be passed to IFWXDataFilter::SetSockets.
PriorityClass
[in] Priority class in which the data filter created will be attached. This is a value from the FwxDataFilterPriorityClass enumerated type.
dwFlags
Specifies the flags for the call. Any combination of the following values is acceptable for the dwFlags parameter.
Value | Description
FWX_FLAG_ADDRESS_BASED | The connection for which the data filter is needed may be created by a different process using the same address.

ppProxyAction
[out] Address of a buffer that received a pointer to the IFWXProxyAction interface on the proxy action object created as a result of this call.

Remarks

This method is an alternative to registering to the corresponding event, comparing the address, and calling IFWXConnection::AttachDataFilter. The Firewall service creates a data filter using the COM interface IClassFactory, when the specified event is detected. The data filter is then attached to the appropriate connection.


IFWXSessionFilter

Each application filter must implement the IFWXSessionFilter interface. The interface is implemented by each session filter object. Each user session may have a different combination of session filters attached to it; however, each session filter is attached to a single user session.

A session-filter object is attached to a user session when the Firewall service calls the IFWXFilter::AttachToSession method.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXSessionFilter Methods | Description
FwxProxyEventHandler | Sink for Firewall service events.
Detach | Called by the Firewall service when the session is shutting down.

Implementation

This interface is implemented by the application filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXSessionFilter::Detach Method

Notifies the session filter to detach from a session. The session filter object should release all references it holds on the session and any related objects.

HRESULT Detach()

Return Values

Value | Meaning
S_OK | The method succeeded.
E_FAIL | The method failed. This will cause the Firewall service to generate an alert.


IFWXSessionFilter::FwxProxyEventHandler Method

Provides the event sink for proxy events relating to the session to which this session filter is attached.

HRESULT ProxyEventHandler(
  const ProxyEvent * pProxyEvent
);

Return Values

Value | Meaning
S_OK | The filter successfully processed the event.
FWX_E_TERMINATING | The filter will not process the event because IFWXSessionFilter::Detach has already been called.
E_OUTOFMEMORY | Insufficient memory or resources to process the event. This will cause the request that generated the event to fail, although a fwx_ConnectionTerminating event will be processed.

Parameters

pProxyEvent
[in] Pointer to a FwxProxyEvent structure that describes the event for which this method is called, and that receives information about the event. For more information, see the documentation for each event type.

Remarks

This method is called when an event occurs for which the filter is registered.

See Also

FwxProxyEvent


IFWXSlowDataFilter

A data-filter object may implement the IFWXSlowDataFilter interface to prevent premature termination of the connection.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXSlowDataFilter Methods | Description
OkToTerminate | Verifies that all data for this connection has been processed.

Implementation

This interface is implemented by the application filter.

Remarks

When a Firewall client application calls the Winsock WSACleanup function, the client DLL will close the Firewall service session. As a result, the Firewall service will terminate all the connections that were created in this session.

In rare circumstances, this may lead to data loss, if the client application relies on TCP/IP for receipt acknowledgement. The connection could be closed after acknowledgement of a packet receipt, because the slow connection delays the receipt of the remainder of the packets. This is not an issue if the client application uses application level acknowledgement.

To prevent data loss in these cases, implement the IFWXSlowDataFilter interface.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXSlowDataFilter::OkToTerminate Method

Verifies that all data for this connection has been processed.

HRESULT OkToTerminate()

Return Values

Value | Meaning
S_OK | The Firewall service can safely terminate the connection.
S_FALSE | Not all data on the connection has been processed.

Remarks

When a data filter returns S_FALSE it is indicating that the Firewall service should not terminate the connection yet. The Firewall service may call this method periodically to check the status of the connection.

This method should take into account reasonable network time-out and eventually return S_OK.


IFWXSocket

The IFWXSocket interface is the Firewall service socket interface.

Note

Before releasing this interface, you must call IFWXSocket::Close or IFWXSocket::Shutdown on it.

Remarks

This interface does not necessarily correspond to a network socket, but allows data filters to work with the data that is flowing through the socket, using a socket-like interface. A network socket implements the IFWXNetworkSocket interface.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXSocket Methods | Description
Send | Sends a buffer asynchronously.
SendTo | Sends a buffer asynchronously to a specific address, on UDP sockets.
Recv | Receives a buffer asynchronously.
Shutdown | Shuts down the socket (half close).
Close | Closes the socket.

Implementation

This interface is implemented by the Firewall service.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXSocket::Close Method

Closes the socket.

HRESULT Close(
  BOOLEAN fAbortive
);

Parameters

fAbortive
[in] Close-type flag. If TRUE, the connection will be hard-closed (RST packet). If FALSE, it will be closed gracefully (FIN packet).

Remarks

A hard close is done by setting the SO_DONTLINGER option in the Winsock setsockopt function.


IFWXSocket::Recv Method

Receives a buffer asynchronously; that is, performs an overlapped receive (or receivefrom operation, depending on the socket type).

HRESULT Recv(
  IFWXIOBuffer * pIOBuffer,
  IFWXIOCompletion * pIFWXIOCompletion,
  UserContextType UserData
);

Parameters

pIOBuffer
[in] Pointer to the buffer that receives the data.

This parameter may be set to NULL, in which case the Firewall service will create the buffer. In this case, the same buffer object can be passed between data filters, and buffer copy will be avoided. The IFWXIOCompletion::CompleteAsyncIO completion method receives a buffer object as one of its arguments.

pIfWXIOCompletion
[in] Pointer to the IFWXIOCompletion interface that receives the completion notification. This parameter is required, it cannot be NULL.
UserData
[in] An opaque value to pass to the IIOCompletion::CompleteAsyncIO notification method. This parameter provides a context to the notification.

Remarks

When you are re-using a user-created buffer (implementing IFWIOBuffer), IFWXSocket::Recv works in Append mode.

The con

Built on Tuesday, May 23, 2000


IFWXSocket::Send Method

Sends a buffer asynchronously; that is, performs an overlapped sendoperation.

HRESULT Send(
  IFWXIOBuffer * pIOBuffer,
  IFWXIOCompletion * pIFWXIOCompletion,
  UserContextType UserData
);

Parameters

pIOBuffer
[in] Pointer to the buffer to send.
pIIOCompletion
[in] Pointer to the IFWXIOCompletion interface that is notified when the send operation is completed. Set this parameter to NULL if notification is not required.
UserData
[in] An opaque value to pass to the IFWXIOCompletion::CompleteAsyncIO notification method. This parameter provides a context to the notification, thereby allowing identification of each send operation.

Remarks

To receive a notification when the send operation is completed, specify an IFWXIOCompletion interface pointer in the pIFWXIOCompletion parameter.

See Also

IFWXIOBuffer


IFWXSocket::SendTo Method

Sends a buffer asynchronously on UDP sockets to a specific address; that is, performs an overlapped sendto operation.

HRESULT SendTo(
  IFWXIOBuffer * pIOBuffer,
  SOCKADDR * Address,
  INT AddressLength,
  IFWXIOCompletion * pIFWXIOCompletion,
  UserContextType UserData
);

Parameters

pIOBuffer
[in] Pointer to the buffer to send.
Address
[in] When calling this method on an external socket, this sockaddr structure should contain the target address for a UDP datagram. When calling this method on an internal socket, this parameter should contain the address of the datagram source. This is typically the Internet address from which the pIOBuffer packet originated. That is, the internal socket is associated with the Internet address of the pIOBuffer packet.
AddressLength
[in] Length, in bytes, of the Address parameter.
pIFWXIOCompletion
[in] Pointer to an IFWXIOCompletion interface that is notified when the send operation is completed. Set this parameter to NULL if notification is not required.
UserData
[in] An opaque value to pass to the IFWXIOCompletion::CompleteAsyncIO notification method. This parameter provides a context to the notification.

Remarks

To receive a notification when the sendto operation is completed, specify a IFWXIOCompletion interface pointer in the pIFWXIOCompletion parameter.


IFWXSocket::Shutdown Method

Starts transport shutdown on this socket.

HRESULT Shutdown(
  BOOLEAN fAbortive
);

Parameters

fAbortive
[in] Close-type flag. If TRUE, the connection will be hard-closed (RST packet). If FALSE, it will be closed gracefully (FIN packet).

Remarks

Shutdown is done with how=SD_SEND. An abortive shutdown is carried out by setting the SO_DONTLINGER option in the Winsock setsockopt function.


Structures

The application filter API uses the following unions and structures:

  • FwxAcceptEvent
  • FwxBindEvent
  • FwxConnectEvent
  • FwxEndConnectionEvent
  • FwxFilterHookEvents
  • FwxGetHostByAddrEvent
  • FwxGetHostByNameEvent
  • FwxListenEvent
  • FwxPortRangeEvents
  • FwxProxyEvent
  • FwxProxyEventParameters
  • FwxUdpDestination


FwxAcceptEvent

The FwxAcceptEvent structure contains parameters for the fwx_AcceptedConnection event.

This event is a notification on a new connection that arrived on a listening socket.

typedef struct {
  LPSOCKADDR RemoteAddress;
  DWORD RemoteAddressLength;
  LPSOCKADDR LocalAddress;
  DWORD LocalAddressLength;
  IFWXConnection * piConnectionAccepted;
  FwxFilterAccess FwxFilterAccess;
} FwxAcceptEvent;

Members

RemoteAddress
[in] Pointer to a sockaddr structure that contains the address of the connecting peer.
RemoteAddressLength
[in] Size, in bytes, of the RemoteAddress member.
LocalAddress
[in] Pointer to a sockaddr structure that contains the local address for this connection.
LocalAddressLength
[in] Size, in bytes, of the LocalAddress member.
piConnectionAccepted
[in] Pointer to the IFWXConnection interface on the Firewall service connection object for the newly accepted connection.
FwxFilterAccess
[in] Access status for the event. This is a value from the FwxFilterAccess enumerated type. This member indicates the current access status. The filter may not directly modify this member. To modify the access status, a filter may call IFWXConnection::SetProtocol or IFWXConnection::Deny.

Remarks

The listening socket was created as a result of a Firewall client call to the bind and listen APIs, or as a result of a filter successfully calling IFWXSession::BindForClient.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

FwxBindEvent, FwxListenEvent


FwxBindEvent

The FwxBindEvent structure ontains parameters for the pe_Bind_Udp and pe_Bind_Tcp events.

These events are the result of Firewall client calling the bind function, or an application filter calling the IFWXSession::BindForClient method.

typedef struct {
  LPSOCKADDR Address;
  DWORD AddressLength;
  IFWXConnection * piConnection;
  FwxFilterAccess FwxFilterAccess;
  GUID ProtocolGuid
} FwxBindEvent;

Members

Address
[in] Pointer to a sockaddr structure that contains the address that the client wants to assign to the socket.
AddressLength
[in] Length, in bytes, of the data pointed to by the Address member.
piConnection
[in] Pointer to the IFWXConnection interface on the Firewall service connection object for this request.
FwxFilterAccess
[in] Access status for the event. This is a value from the FwxFilterAccess enumeration. This member indicates the current access status. The filter may not directly modify this member. To modify the access status, a filter may call IFWXConnection::SetProtocol or IFWXConnection::Deny.
ProtocolGuid
[in] The globally unique identifier (GUID) for the protocol, if known to the Firewall service. If the protocol is not known, this parameter has the value GUID_NULL.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


FwxConnectEvent

The FwxConnectEvent structure contains parameters for the fwx_Connect_Tcp event.

This information concerns a connect call made by a Firewall client, or a TCP connection initiated by a SecureNAT client.

typedef struct {
  LPSOCKADDR Address;
  DWORD AddressLength;
  IFWXConnection * piConnection;
  FwxFilterAccess FwxFilterAccess;
} FwxConnectEvent;

Members

Address
[in] Pointer to a sockaddr structure that contains the address to which the client is attempting to connect.
AddressLength
[in] Length, in bytes, of the data pointed to by the Address member.
piConnection
[in] Pointer to the IFWXConnection interface on the Firewall service connection object for this request.
FwxFilterAccess
[in] Access status for the event. This is a value from the FwxFilterAccess enumerated type. This member indicates the current access status. The filter may not directly modify this member. To modify the access status, a filter may call IFWXConnection::SetProtocol or IFWXConnection::Deny.

Remarks

Secure NAT connections will generate an event only if the connection is to a port that is a primary port of a predefined protocol (including protocols defined by IFWXFilterAdmin::RegisterProtocolForFilter), or to an address specified in a call to IFWXSession::AllowFutureConnect. Other connection attempts are dropped by the system before they reach the proxy. For more information about NAT and SecureNAT, see Secure Network Address Translation.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

FwxProxyEventParameters, FwxProxyEventType


FwxEndConnectionEvent

The FwxEndConnectionEvent structure contains parameters for the fwx_ConnectionTerminating event.

This event occurs as a result of a connection being terminated. A filter that holds a reference to the Firewall service connection object must release the reference so that the connection object can be deleted.

typedef struct {
  IFWXConnection * piConnection;
} FwxEndConnectionEvent;

Members

piConnection
[in] Pointer to the IFWXConnection interface on the Firewall service connection object that is terminating. References to this object must be released in response to the event.

Remarks

It is unnecessary to register for this event in the IFWXFilter::FilterInit method because a session filter is never attached in response to this event.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


FwxEstablishedConnectionEvent

The FwxEstablishedConnectionEvent structure contains parameters for the fwx_EstablishedConnection event.

This event provides notification of connections established for IFWXSession::AllowFutureConnect, IFWXSession::BindForClient, and IFWXSession::RedirectConnections methods. When a connection is made as a result of a call to one of these three methods, the Firewall service creates this event.

typedef struct _EstablishedConnectionEvent {
  INT Protocol;
  [ref] LPSOCKADDR Address;
  DWORD AddressLength;
  IFWXConnection *piConnection;
  UserContextType UserContext;
} FwxEstablishedConnectionEvent;

Members

Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The connection will use the TCP protocol.
FWX_PROTOCOL_UDP | The connection will use the UDP protocol.

Address
[in] Pointer to a sockaddr structure that contains the address to which the client is attempting to connect.
AddressLength
[in] Length, in bytes, of the data pointed to by the Address member.
piConnection
[in] Pointer to the IFWXConnection interface on the Firewall service connection object that is terminating. References to this object must be released in response to the event.
UserContext
[in] User context for the connection. This is identical to the UserContextType parameter of the function that created the connection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


FwxFilterHookEvents

The FwxFilterHookEvents structure defines all the events that a filter wants to monitor. When a user session generates an event that the filter monitors, a session-filter object is created and notified of the event. At this point, the session filter may change the set of events for that specific client session.

typedef struct {
  DWORD dwGlobalEvents;
  DWORD dwNumPortRanges;
  PortRangeEvents * PortRangeEvents;
} FwxFilterHookEvents;

Members

dwGlobalEvents
A combination of FwxProxyEventType values combined with a combination of FwxProxyEventSource values using the bitwise OR operator.

Specifies events for notification on all ports, or events that are not associated with port numbers (name resolution).

dwNumPortRanges
Number of entries in the array specified by the PortRangeEvents member.
PortRangeEvents
Pointer to an array of FwxPortRangeEvents structures.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXFilter::AttachToSession, IFWXFilter::FilterInit, IFWXProxy::DuplicateFilterHookEvents


FwxGetHostByAddrEvent

The FwxGetHostByAddrEvent structure contains parameters for the fwx_GetHostByAddr event.

This event is a notification on an Firewall client operation that uses the Winsock gethostbyaddr function. It allows the filter to modify or block a request that uses gethostbyaddr by using the IFWXGetXByY::SetResult or IFWXGetXByY::Deny method. Two events are generated, one before and one after the actual name resolution.

typedef struct {
  BYTE * Address;
  DWORD AddressLength;
  INT AddressType;
  LPHOSTENT Hostent;
  DWORD HostentLength;
  BOOL fBeforeAction;
  FwxFilterAccess FwxFilterAccess;
  IFWXGetXByY * piGetXByY;
} FwxGetHostByAddrEvent;

Members

Address
[in] Address being looked up in network byte order.
AddressLength
[in] Size in bytes of the buffer pointed to by the Address member.
AddressType
[in] Type of address, such as the AF_INET address family type (defined as TCP, UDP, and other associated Internet protocols). Address family types and their corresponding values are defined in winsock2.h.
Hostent
[in] Pointer to a buffer containing the response hostent structure. The buffer contains a valid hostent structure if the fBeforeAction member is FALSE. Otherwise, the value of the Hostent member is undefined.
HostentLength
[in] Size, in bytes, of the buffer pointed to by the Hostent member.
fBeforeAction
Before-action flag. The value of this flag is TRUE when called before name resolution is done.

It is FALSE when the gethostbyaddr function is called after name resolution is done. The buffer contains a valid hostent structure if the fBeforeAction member is FALSE.

FwxFilterAccess
[in] Access status for the event. This is a value from the FwxFilterAccess enumerated type. This member indicates the current access status. The filter may call the IFWXGetXByY::Deny method to modify the access status.
piGetXByY
[in] Pointer to a IFWXGetXByY interface that can be used to control the outcome of the name query.

Remarks

This event is generated only for Firewall clients (fwxSourceWSP), it is not generated for Secure NAT clients.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXGetXByY


FwxGetHostByNameEvent

The FwxGetHostByNameEvent structure contains parameters for the fwx_GetHostByName event.

This event is a notification on a gethostbyname operation performed by a Firewall client. It allows the filter to modify or block a gethostbyname request. Two events are generated, one before and one after actual name resolution.

typedef struct {
  LPSTR Hostname;
  LPHOSTENT Hostent;
  DWORD HostentLength;
  BOOL fBeforeAction;
  FwxFilterAccess FwxFilterAccess;
  IFWXGetXByY * piGetXByY;
} FwxGetHostByNameEvent;

Members

Hostname
[in] Pointer to the host name being looked up.
Hostent
[in, out] Pointer to a buffer for setting the response hostent structure. The buffer contains a valid hostent structure if the fBeforeAction member is FALSE.
HostentLength
[in] Size, in bytes, of the buffer pointed to by the Hostent member.
fBeforeAction
Before-action flag. It is TRUE when called before name resolution is done.

It is FALSE when this gethostbyname is called after name resolution is done. The buffer contains a valid hostent structure if the fBeforeAction member is FALSE.

FwxFilterAccess
[in] Access status for the event. This is a value from the FwxFilterAccess enumerated type. This member indicates the current access status. The filter may call the IFWXGetXByY::Deny method to modify the access status.
piGetXByY
[in] Pointer to a IFWXGetXByY interface that can be used to control the outcome of the name query.

Remarks

This event is generated only for Firewall clients (fwxSourceWSP), not for SecureNAT clients.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXGetXByY


FwxListenEvent

The FwxListenEvent structure contains parameters for the fwx_Listen event.

This is the result of Firewall client calling the listen function, or an application filter calling the IFWXSession::BindForClient method.

typedef struct {
  LPSOCKADDR Address;
  DWORD AddressLength;
  IFWXConnection * piConnection;
} FwxListenEvent;

Members

Address
[in] Pointer to a sockaddr structure that contains the address that the socket was assigned. This is the same as the result of calling the getsockname function on the socket.
AddressLength
[in] Length, in bytes, of the data pointed to by the Address member.
piConnection
[in] Pointer to the IFWXConnection interface on the Firewall service connection object for this request.

Remarks

There is no way for a filter to fail this request because client applications do not expect the listen function to fail. The place for a filter to deny inbound access is in the bind request or when a connection actually arrives. For example, in the fwx_AcceptedConnection event.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


FwxPortRangeEvents

The FwxPortRangeEvents structure defines a set of events for a port range.

typedef struct {
  USHORT StartPort;
  USHORT EndPort;
  DWORD dwSocketEvents;
} FwxPortRangeEvents;

Members

StartPort
First port in the range.
EndPort
Last port in the range.
dwSocketEvents
FwxProxyEventType values combined with FwxProxyEventSource values using the bitwise OR operator.

Remarks

The following events do not have a port associated with them, and should not be specified with FwxPortRangeEvents: fwx_ConnectionTerminating fwx_GetHostByName fwx_GetHostByAddr.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

FwxFilterHookEvents


FwxProxyEvent

The FwxProxyEvent structure describes a proxy event.

typedef struct {
  ProxyEventType EventType;
  ProxyEventSource EventSource;
  ProxyEventParameters Parameters;
} FwxProxyEvent;

Members

EventType
Type of event. This member is a value from the FwxProxyEventType enumerated type.
EventSource
Source of the event. This member is a value from the FwxProxyEventSource enumerated type.
Parameters
Parameters specific to the proxy event.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


FwxProxyEventParameters

The FwxProxyEventParameters structure is a union of event-specific parameters.

[switch_type(ProxyEventType)]
typedef union _tagProxyEventParameters {
  [case (pe_Connect_Tcp)]
  struct ConnectEvent       Connect;
  [case (pe_Udp_Destination)]
  struct UdpDestination     UdpDest;
  [case (pe_Bind_Udp, pe_Bind_Tcp)]
  struct BindEvent          Bind;
  [case (pe_Listen)]
  struct ListenEvent        Listen;
  [case (pe_AcceptedConnection)]
  struct AcceptEvent        Accept;
  [case (pe_GetHostByAddr)]
  struct GetHostByAddrEvent GetHostByAddr;
  [case (pe_GetHostByName)]
  struct GetHostByNameEvent GetHostByName;
  [case (pe_ConnectionTerminating)]
  struct EndConnectionEvent EndConnect;
} FwxProxyEventParameters;

Members

Connect
Parameters for an fwx_Connect_Tcp event. For more information see FwxConnectEvent.
UdpDest
UdpDest parameters for a fwx_Udp_Destination event. For more information see FwxUdpDestination.
Bind
Parameters for fwx_Bind_Tcp, and fwx_Bind_Udp events. For more information see FwxBindEvent.
Listen
Parameters for an fwx_Listen event. For more information see FwxListenEvent.
Accept
Parameters for an fwx_AcceptedConnection event. For more information see FwxAcceptEvent.
GetHostByAddr
Parameters for an fwx_GetHostByAddr event. For more information see FwxGetHostByAddrEvent.
GetHostByName
Parameters for an fwx_GetHostByName event. For more information see FwxGetHostByNameEvent.
EndConnect
Parameters for an fwx_ConnectionTerminating event. For more information see FwxEndConnectionEvent.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


FwxUdpDestination

The FwxUdpDestination structure contains parameters for the fwx_Udp_Destination event.

This event is generated when a UDP destination is generated, which occurs under the following circumstances:

  • A Firewall client application calls the connect function on a remote UDP socket.
  • A proxy client (either SecureNAT or Firewall service) attempts a sendto operation to a new destination.
  • A packet has just been sent to the client from the given address.
typedef struct {
  LPSOCKADDR Address;
  DWORD AddressLength;
  IFWXConnection * piConnection;
  FwxFilterAccess FwxFilterAccess;
} FwxUdpDestination;

Members

Address
[in] Pointer to a sockaddr structure that contains the address to which the client is attempting to connect.
AddressLength
[in] Length, in bytes, of the data pointed to by the Address member.
piConnection
[in] Pointer to the IFWXConnection interface on the Firewall service connection object for this request.
FwxFilterAccess
[in] Access status for the event. This is a value from the FwxFilterAccess enumerated type. On input, this member indicates the current access status. The filter may not modify this member.

Remarks

The Firewall service keeps a cache of known UDP sources and destinations for each UDP connection object. An event is only generated for destinations that are not in this cache.

The FwxFilterAccess member for the event pertains only to outgoing packets to the destination. The filter may not directly modify this member. To modify the access status, a filter may call IFWXConnection::SetProtocol or IFWXConnection::Deny. Data filters installed by a handler for this event are associated with the destination, and may be detached by the Firewall service when it is invalidating a cached destination.

Although an fwx_Udp_Destination event may be generated as a result of an incoming datagram, it is not intended for interception of inbound traffic. To examine inbound datagrams, use the fwx_Bind_Udp event.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


Filter Enumerated Types

The application filter API uses the following enumerated types:

  • FwxFilterAccess
  • FwxDataFilterPriorityClass
  • FwxProxyEventSource
  • FwxProxyEventType


FwxFilterAccess

The FwxFilterAccess enumerated type contains values that indicate the type of access permission for a filter event.

enum FwxFilterAccess {
  FWX_ALLOW,
  FWX_DENY,
  FWX_PASS,
  FWX_EMULATE
};

Elements

FWX_ALLOW
Grants permission. Overrides the default (built in) protocol/permission check.
FWX_DENY
Denies the action.
FWX_PASS
Allows access if none of the other filters (including the built-in rules) denies it and at least one filter (including the built-in) allows it. This is the default value for FwxFilterAccess.
FWX_EMULATE
Signals that the filter wants to intercept and implement the request, emulating an external connection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

FwxGetHostByNameEvent, FwxGetHostByAddrEvent, FwxUdpDestination, FwxAcceptEvent, FwxBindEvent, FwxConnectEvent


FwxDataFilterPriorityClass

The FwxDataFilterPriorityClass enumerated type contains values used to specify the order of data filters for the same connection. Within the same priority class, the order will be arbitrary.

enum FwxDataFilterPriorityClass {
  dfpc_NAT,
  dfpc_Internal,
  dfpc_PostTrust,
  dfpc_Middle,
  dfpc_PreTrust,
  dfpc_External,
  dfpc_Emulation
};

Elements

dfpc_NAT
As close to the client as possible. This should be used only if the data filter is a SecureNAT editor.
dfpc_Internal
As close to the client as possible for a non-SecureNAT filter.
dfpc_PostTrust
Close to the client side.
dfpc_Middle
Middle of the chain. Virus scanners should use this priority.
dfpc_PreTrust
Close to the server side.
dfpc_External
As close to the external source as possible.
dfpc_Emulation
Used by emulation filters. The filter is the source of the data.

Remarks

Each priority setting is defined as being closer to the client or closer to the server. A data filter that is closer to the client is likely to be the first to examine data flowing from the client, and unlikely to be the first to examine data flowing to the client. A data filter that is closer to the server is likely to be the first to examine data flowing from the server to the client, and unlikely to be the first to examine data flowing from the client to the server.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXConnection::AttachDataFilter, IFWXConnection::AttachDataFilterWithDestination, IFWXConnection::EmulateConnection, IFWXSession::SetDataFilterFactory


FwxProxyEventSource

The FwxProxyEventSource enumerated type contains values that indicate the source of an event. The source can be either a SecureNAT client or a Firewall client.

enum FwxProxyEventSource {
  fwxSourceWSP,
  fwxSourceNAT
};

Elements

fwxSourceWSP
Source is a Firewall client.
fwxSourceNAT
Source is NAT.

Remarks

Use the fwxSourceNAT macro to set both the fwxSourceWSP and fwxSourceWSP values. For more information on developing filters for SecureNAT and Firewall clients, see Filter Requirements for SecureNAT Clients, and Filter Requirements for Firewall Clients.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

FwxFilterHookEvents, FwxPortRangeEvents, FwxProxyEvent, FwxGetHostByNameEvent


FwxProxyEventType

The FwxProxyEventType enumerated type defines the types of events to which a filter may hook. Each value in this enumeration is a bit. Values can be combined using the bitwise OR operator to specify a set of events.

enum FwxProxyEventType {
  fwx_Connect_Tcp,
  fwx_Udp_Destination,
  fwx_Bind_Tcp,
  fwx_Bind_Udp,
  fwx_Listen,
  fwx_AcceptedConnection,
  fwx_GetHostByName,
  fwx_GetHostByAddr,
  fwx_ConnectionTerminating
  fwx_EstablishedConnection
};

Elements

fwx_Connect_Tcp
Connect request for TCP sockets. For more information, see FwxConnectEvent.
fwx_Udp_Destination
Connect request for UDP sockets. For more information, see FwxUdpDestination.
fwx_Bind_Tcp
Bind request for TCP sockets. For more information, see FwxBindEvent.
fwx_Bind_Udp
Bind request for UDP sockets. For more information, see FwxBindEvent.
fwx_Listen
Listen on a TCP socket. For more information, see FwxListenEvent.
fwx_AcceptedConnection
Actual inbound connection on a listening TCP socket. For more information, see FwxAcceptEvent.
fwx_GetHostByName
The Firewall client calls the gethostbyname function. This event can be generated only by a Firewall client. It will not be generated for a SecureNAT client. For more information, see FwxGetHostByNameEvent.
fwx_GetHostByAddr
The Firewall client calls the gethostbyaddr function. This event can be generated only by a Firewall client. It will not be generated for a Secure NAT client. For more information, see FwxGetHostByAddrEvent.
fwx_ConnectionTerminating
Notification before shutting down a connection object. For more information, see FwxEndConnectionEvent.
fwx_EstablishedConnection
Notification for connections established for IFWXSession::AllowFutureConnect, IFWXSession::BindForClient, and IFWXSession::RedirectConnections methods. This event is created by the Firewall service. For more information see FwxEstablishedConnectionEvent.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXConnection, IFWXSession::SetDataFilterFactory


Cache Reference

The cache reference provides information on the interfaces you can use to extend cache functionality.

This section contains the following topic:

  • Cache Interfaces


Cache Interfaces

Cache interfaces expose the COM objects needed to extend the cache functionality.

The ISA cache interfaces defined in this section include:

  • IFPCCacheContents


IFPCCacheContents

IFPCCacheContents is the interface for the FPCCacheContents object, which specifies to the cache the URLs that need to be pre-fetched.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type information interfaces.
GetTypeInfo | Gets the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer dispatch identifiers (DISPIDs).
Invoke | Provides access to properties and methods exposed by an object.

IFPCCacheContents Methods | Description
FetchURL | Causes the Web proxy service to retrieve an object and store it in the cache.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


IFPCCacheContents::FetchUrl Method

Causes the Web proxy service to retrieve an object and store it in the cache.

STDMETHODIMP IFPCCacheContents::FetchUrl(
  BSTR lpszFetchUrl,
  BSTR lpszCacheUrl,
  long TtlInMinutes,
  long Flags
);

Return Values

The method returns an HRESULT to indicate success or failure. If the result is an error, the error code portion of the HRESULT (the low 16 bits of the value) may be a value defined by Microsoft® Win32®, WinInet, or Windows Sockets (Winsock).

Parameters

lpszFetchUrl
[in] The URL of the object to be fetched. The URL may be any combination of protocol, domain and path that the Web proxy service would normally be able to access. The Web proxy service currently supports the HTTP, FTP and Gopher protocols.
lpszCacheUrl
[in] The URL that clients will use to retrieve the fetched object from the Web proxy service's cache. The URL must include one of the protocols supported by the Web proxy service for cache retrieval (HTTP or FTP) but the domain specified need not be accessible from the proxy computer because the data itself will have been read from FetchUrl. The URL may be the same as FetchUrl.
TtlInMinutes
[in] Specifies the Time to Live (TTL), in minutes, that the object should be served from the Web proxy service cache. After the TTL has passed, the object is said to have "expired" and will no longer be returned to requesting clients if the proxy has not first verifyied that the object is unchanged. In general, the application calling FetchUrl will want to set a TTL that is large enough to ensure that the object will not expire before the application next refreshes it. Note that both fresh and expired objects can be deleted from the cache if the cache directories become full.

This parameter is ignored unless either the fpcFetchTtlIfNone or fpcFetchTtlOverride flag is included in the Flags parameter. If neither flag is specified, the proxy's normal TTL computation mechanism will be used for the object.

Flags
[in] A set of bit flags to control the behavior of this function. One of the following flag values may be set to control the TTL of the object in the Web proxy service's cache.
Value | Description
fpcFetchTtlOverride | (value: 1) The TtlInMinutes parameter will be used to set the TTL for the object unless the publishing Web server has supplied an "Expires" or "Cache-Control: max-age" HTTP header.
fpcFetchTtlOverride | (value: 2) The TtlInMinutes parameter will be used to set the TTL for the object regardless of any "Expires" or "Cache-Control: max-age" HTTP header that the publishing Web server may have included with the object. Exercise caution when overriding a TTL for objects that were authored by another party because this might lead to objects being cached for longer than their intended lifetimes.

If neither flag is set, the Web proxy service will use its normal TTL computation mechanism for the object, which uses an "Expires" or "Cache-Control: max-age" HTTP header if available. Otherwise, it estimates a good TTL value based on the time that has elapsed since the object was last modified.

In addition, one or more of the following flag values may be set:
Value | Description
fpcFetchSynchronous | (value: 4) This function will not return to the caller until the fetch has completed and the object is stored in the cache, or until an error occurs in the processing of the request, which ends the operation. If this flag is not specified, the function will return immediately and the fetch will complete asynchronously to the caller, in which case it is not possible to determine whether the fetch completed successfully.
fpcFetchNoArrayRouting | (value: 8) If the proxy server is a member of an array, store this object in the cache of this particular proxy even if CARP, the normal array cache-sharing mechanism, would indicate that the object should be cached on a different array member. If this flag is not specified, the object will be automatically cached on the array member that the CARP algorithm designates. This flag is ignored if the Web proxy service is not a member of an array.
fpcFetchForceCache | (value: 16) Cache the object even if the caching rules in the HTTP specification would normally prohibit this object from being cached (for example, if the object contains a "Cache-Control: no-cache" HTTP header or the response indicates a server error). Exercise caution when using this flag for objects that were authored by another party. There is often a good reason why the data could not be cached and why caching it might cause the site to not function properly or might even be a violation of your license agreement for the use of the data. If CacheUrl contains a question mark, this flag alone will not allow the object to be cached. Use the FPCCacheConfiguration::CacheQuestionUrls property to enable caching URLs containing question marks.

Remarks

To retrieve a Hypertext Transfer Protocol (HTTP) object in response to a FetchUrl call, the Web proxy service uses the normal HTTP GET method to the URL specified by lpszFetchUrl. If there is already a cached copy (which was either loaded into the proxy previously by normal operations or by an earlier call to FetchUrl) of the URL specified by lpszCacheUrl, the proxy will include an "If-Modified-Since" HTTP header in the request (also known as a conditional GET). The response to a conditional GET may be either a new copy of the data, which will be stored in the cache, or an HTTP status code 304 "Not Modified" response, which will cause the proxy to extend the TTL of the object without changing the contents of the data in the cache.

To delete an HTTP object from the cache, set lpszFetchUrl =<empty string>, and lpszCacheUrl = <cachedURL>. When you delete an HTTP object using FetchUrl, you can perform the operation synchronously or asynchronously, and the TTL must be set to 0.

Note ERROR_INTERNET_UNABLE_TO_CACHE_FILE (decimal value 12158, hex value 2f7e) is a new value that is not present in all versions of WinInet include files. This error code is returned if the HTTP headers in the object or other factors prohibited the proxy from caching the object. The caller may still be able to force the object into the cache using the fpcFetchForceCache flag.


ISAPI Reference

The ISAPI Reference section contains the following topics:

  • Filter Entry Points
  • Notification Structures
  • Event Notifications


Filter Entry Points

Web (ISAPI) filters for the ISA Web proxy service implement the following standard entry points:

  • GetFilterVersion
  • HttpFilterProc
  • TerminateFilter


GetFilterVersion

The GetFilterVersion function is the first entry-point function called by the ISA Web proxy service on your Web (ISAPI) filter, and must be present for the filter to work properly. Its declaration is:

BOOL WINAPI GetFilterVersion(
  PHTTP_FILTER_VERSION pVer
);

Parameters

pVer
Points to the HTTP_FILTER_VERSION structure that contains both the version information for the server and members with which the filter can indicate filter version number, notifications, and priority desired. There is also a space for the filter application to provide a descriptive text.

Return values

If this function returns TRUE, the filter will remain loaded. If the function returns FALSE, the filter will not receive any event notifications.

Note It is important to register only for those notifications that are necessary for your filter's purposes. Registering for additional notifications will reduce performance.


HttpFilterProc

Whenever a notification event for which the filter has registered (in GetFilterVersion) occurs, the ISA Web proxy service calls HttpFilterProc. The Web proxy service uses this function to pass information and control to the Web (ISAPI) filter. The declaration of HttpFilterProc is:

DWORD WINAPI HttpFilterProc(
  PHTTP_FILTER_CONTEXT pfc,
  DWORD notificationType,
  LPVOID pvNotification
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP transaction.
notificationType
Points to a bitmask that indicates the type of notification event that is being processed. See Event Notifications for a list of event-notification types.
pvNotification
The notification-specific structure that contains more information about the current context of the request.
Notification Type | pvNotification Points To …
SF_NOTIFY_READ_RAW_DATA | HTTP_FILTER_RAW_DATA
SF_NOTIFY_SEND_RAW_DATA | HTTP_FILTER_RAW_DATA
SF_NOTIFY_PREPROC_HEADERS | HTTP_FILTER_PREPROC_HEADERS
SF_NOTIFY_AUTHENTICATION | HTTP_FILTER_AUTHENT
SF_NOTIFY_URL_MAP | HTTP_FILTER_URL_MAP
SF_NOTIFY_LOG | HTTP_FILTER_LOG
SF_NOTIFY_ACCESS_DENIED | HTTP_FILTER_ACCESS_DENIED
SF_NOTIFY_SEND_RESPONSE | HTTP_FILTER_SEND_RESPONSE

Note SF_NOTIFY_SEND_RESPONSE is not used when the ISA Web proxy service sends a response. However, it is called when a filter generates a response itself using ServerSupportFunction (SF_REQ_SEND_RESPONSE_HEADERS).

Return Values

Returns one of the following values that indicate how the application handled the event.

Value | Meaning
SF_STATUS_REQ_FINISHED | The filter has handled the HTTP request. The server should disconnect the session.
SF_STATUS_REQ_FINISHED_KEEP_CONN | Treated the same as SF_STATUS_REQ_FINISHED. After this notification is received, the connection is closed.
SF_STATUS_REQ_NEXT_NOTIFICATION | The next filter in the notification chain should be called.
SF_STATUS_REQ_HANDLED_NOTIFICATION | This filter handled the notification. No other handlers should be called for this particular notification type.
SF_STATUS_REQ_ERROR | An error occurred. The server should call GetLastError and indicate the error to the client. The HTTP request will generally be aborted when this status is returned. The client should call SetLastError with the nature of the failure.
SF_STATUS_REQ_READ_NEXT | The filter is an opaque stream filter (encrypted/compressed HTTP requests) and the session parameters are being negotiated. This is valid only for raw-read notification. This value indicates that the full request has not yet been received; the Web server should issue another read and notify the filter with the additional data read.

Remarks

This function usually serves as the dispatch for a Web (ISAPI) filter. Separate functions are often created to serve as handlers for the separate notifications, especially if the handling code is complicated.


TerminateFilter

This function indicates to the filter that it is going to be removed from memory. When this function is called, you should make sure that the filter closes any attachments it has made to system resources.

The TerminateFilter function is declared as:

BOOL WINAPI TerminateFilter(
  DWORD dwFlags
);

Parameters

dwFlags
No values for dwFlags have been identified at this time.


Notification Structures

The following structures are used by Web (ISAPI) filters:

  • HTTP_FILTER_ACCESS_DENIED
  • HTTP_FILTER_AUTHENT
  • HTTP_FILTER_CONTEXT
  • HTTP_FILTER_LOG
  • HTTP_FILTER_PREPROC_HEADERS
  • HTTP_FILTER_RAW_DATA
  • HTTP_FILTER_SEND_RESPONSE
  • HTTP_FILTER_URL_MAP
  • HTTP_FILTER_VERSION

All function declarations and data structures are available in the Web (ISAPI) filter header file httpfilt.h in the Windows 2000 SDK.


HTTP_FILTER_ACCESS_DENIED

The ISA Web proxy service includes a pointer to this structure when a user is presented with an Access Denied error message. If your filter should be notified for this event, it should register for the SF_NOTIFY_ACCESS_DENIED event.

typedef struct _HTTP_FILTER_ACCESS_DENIED {
  const CHAR * pszURL;
  const CHAR * pszPhysicalPath;
  DWORD dwReason;
} HTTP_FILTER_ACCESS_DENIED, *PHTTP_FILTER_ACCESS_DENIED;

Members

pszURL
Points to a null-terminated string that specifies the URL that requested access to the resource.
pszPhysicalPath
The physical path of the resource that was requested.
dwReason
A DWORD date type containing flags that indicate the reasons for the denial. Can have one of the following values.
Value | Meaning
SF_DENIED_LOGON | The client could not be logged on.
SF_DENIED_RESOURCE | The resource was denied by a Windows discretionary access control list (DACL).
SF_DENIED_FILTER | A Web (ISAPI) filter denied the request.
SF_DENIED_APPLICATION | An ISAPI extension or CGI application denied the request.
SF_DENIED_BY_CONFIG | The server configuration denied the request. For example, disabling anonymous requests on the server would generate this filter notification when a user without credentials tried to make a request to the server.

Remarks

This structure indicates that access to the requested resource has been denied by the server. The structure is generated when there has been a logon failure, or if a user requests a resource that has an associated DACL that does not include the logged-on user.

The server will automatically include the supported authentication schemes when an ISAPI extension, filter, or CGI script returns a 401 Access Denied error code.


HTTP_FILTER_AUTHENT

The ISA Web proxy service includes a pointer to this structure when it is authenticating a user with either anonymous or Basic authentication schemes. If your filter should be notified for this event, it should register for the SF_NOTIFY_AUTHENTICATION event.

typedef struct _HTTP_FILTER_AUTHENT {
  CHAR * pszUser;
  DWORD cbUserBuff;
  CHAR * pszPassword;
  DWORD cbPasswordBuff;
} HTTP_FILTER_AUTHENT, *PHTTP_FILTER_AUTHENT;

Members

pszUser
Points to a string containing the user name for this request. An empty string indicates an anonymous user.
cbUserBuff
The size of the buffer pointed to by pszUser. This is guaranteed to be at least SF_MAX_USERNAME.
pszPassword
Points to a string containing the password for this request.
cbPasswordBuff
The size of the buffer pointed to by pszPassword. This is guaranteed to be at least SF_MAX_PASSWORD.

Remarks

When the server is about to authenticate the client, this structure is pointed to by the pvNotification parameter in the HttpFilterProc function when the notificationType parameter is SF_NOTIFY_AUTHENTICATION. The pszUser and pszPassword members contain the information sent by the client. After exiting this function, these values must represent a valid Windows user account and password. ISA Web proxy will then impersonate this account in order to gain access to resources. If the authentication method used is integrated Windows authentication the password value will not be available.


HTTP_FILTER_CONTEXT

This structure is used by HTTP_FILTER_PROC to obtain information about the current request.

typedef struct _HTTP_FILTER_CONTEXT {
  DWORD cbSize;
  DWORD Revision;
  PVOID ServerContext;
  DWORD ulReserved;
  BOOL fIsSecurePort;
  PVOID pFilterContext;
  BOOL (WINAPI * GetServerVariable);
  BOOL (WINAPI * AddResponseHeaders);
  BOOL (WINAPI * WriteClient);
  VOID * (WINAPI * AllocMem);
  BOOL (WINAPI * ServerSupportFunction);
} HTTP_FILTER_CONTEXT, *PHTTP_FILTER_CONTEXT;

Members

cbSize
The size of this structure, in bytes.
Revision
The revision level of this structure. This is less than or equal to the version of the document HTTP_FILTER_REVISION.
ServerContext
Reserved for server use.
ulReserved
Reserved for server use.
fIsSecurePort
A value of TRUE indicates that this event is over a secure port. A value of FALSE indicates that the event is not over a secure port.
pFilterContext
Pointer to any context information that the filter wants to associate with this request. Any memory associated with this request can be safely freed during the SF_NOTIFY_END_OF_NET_SESSION notification.
GetServerVariable
Pointer to a function that retrieves information about the server and this connection. For some notifications, some variables may not be defined. For example, notifications which occur before PREPROC_HEADERS, such as the READ_RAW_DATA notification, may not be defined.
AddResponseHeaders
Pointer to the AddResponseHeaders function that adds a header to the HTTP response.
WriteClient
Pointer to the WriteClient function that sends raw data back to the client.
AllocMem
Pointer to the AllocMem function used to allocate memory. Any memory allocated with this function will automatically be freed when the session ends.
ServerSupportFunction
Pointer to the ServerSupportFunction function used to extend the Web (ISAPI) filter functions. Parameters are specific to the extensions.


AddResponseHeaders

Points to the AddResponseHeaders function that adds a header to the HTTP response.

The AddResponseHeaders function is declared as:

BOOL WINAPI * AddResponseHeaders(
  PHTTP_FILTER_CONTEXT pfc,
  LPSTR lpszHeaders,
  LPSTR dwReserved
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP transaction.
lpszHeaders
Points to a string that contains the headers to add. The string should be in the following format:
header:value\r\n
dwReserved
Reserved for future use. This must be zero.

Remarks

AddResponseHeaders() can be used to add headers for clients before the server processes the request, but not during or after HTTP_FILTER_SEND_RESPONSE notification. If you need to add a header when the HTTP_FILTER_SEND_RESPONSE notification occurs, you can do so by using the AddHeader member of the HTTP_FILTER_SEND_RESPONSE structure.


AllocMem

Points to the AllocMem function that is used to allocate memory. Any memory allocated with this function will automatically be freed when the session ends.

The AllocMem callback function allocates memory from the process heap to a buffer. Any memory allocated with this function will automatically be freed by the ISA Web proxy service when the session ends.

The AllocMem function is declared as:

VOID * WINAPI * AllocMem(
  PHTTP_FILTER_CONTEXT pfc,
  DWORD cbSize,
  DWORD dwReserved
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current active HTTP transaction.
cbSize
Indicates the size of the buffer to be allocated, in bytes.
dwReserved
Reserved for use by the server.


GetServerVariable

Pointer to a function that retrieves information about the server and this connection. For some notifications, some variables might not be defined. For example, notifications that occur before PREPROC_HEADERS, such as the READ_RAW_DATA notification, may not be defined.

Some server variables, such as Request_Method and Content_Length are embedded in the EXTENSION_CONTROL_BLOCK structure. You can use GetServerVariable to obtain information about the request or server that is not included in the EXTENSION_CONTROL_BLOCK.

The declaration of GetServerVariable is:

BOOL WINAPI GetServerVariable(
  HCONN hConn,
  LPSTR lpszVariableName,
  LPVOID lpvBuffer,
  LPDWORD lpdwSizeofBuffer
);

Parameters

hConn
Specifies the connection handle.
lpszVariableName
A null-terminated string that indicates which variable is requested. The following table lists the possible variables. Variables supported by IIS, but not by ISA, are presented in this table, with information on how the ISA Web proxy service responds to the variable.
Variable | Description
ALL_HTTP | Retrieves all HTTP headers that were received. These variables are of the form HTTP_header field name. The headers consist of a null-terminated string with the individual headers separated by line feeds.
ALL_RAW | Retrieves all headers in raw form. The header names and values appear as they are sent by the client. Currently, this value is primarily used by proxy servers and similar applications.
APPL_MD_PATH | Not supported in ISA; will always return the error (ERROR_INVALID_INDEX).
APPL_PHYSICAL_PATH | Not supported in ISA; will always return the error (ERROR_INVALID_INDEX).
AUTH_PASSWORD | Specifies the value entered in the client's authentication dialog. This variable is only available if Basic authentication is used.
AUTH_TYPE | Specifies the type of authentication used. If the string is empty, then no authentication is used. Possible values are Kerberos, user, Secure Sockets Layer (SSL) or Private Communication Technology (PCT), Basic, and integrated Windows authentication.
AUTH_USER | Specifies the value entered in the client's authentication dialog box.
CERT_COOKIE | Specifies a unique identifier (ID) for a client certificate. Returned as a string. Can be used as a signature for the entire client certificate.
CERT_FLAGS | If bit0 is set to 1, a client certificate is present. If bit1 is set to 1, the certification authority (CA) of the client certificate is invalid; that is, it is not on this server's list of recognized CAs.
CERT_ISSUER | Specifies the issuer field of the client certificate. For example, the codes might be O=MS, OU=IAS, CN=user name, C=USA, and so on.
CERT_KEYSIZE | Specifies the number of bits in the SSL connection key size.
CERT_SECRETKEYSIZE | Specifies the number of bits in the server certificate private key.
CERT_SERIALNUMBER | Specifies the serial-number field of the client certificate.
CERT_SERVER_ISSUER | Specifies the issuer field of the server certificate.
CERT_SERVER_SUBJECT | Specifies the subject field of the server certificate.
CERT_SUBJECT | Specifies the subject field of the client certificate.
CONTENT_LENGTH | Specifies the number of bytes of data that the script or extension can expect to receive from the client. This total does not include headers.
CONTENT_TYPE | Specifies the content type of the information supplied in the body of a request for a power-on self test (POST).
LOGON_USER | The Windows account that the user is logged into.
HTTPS | Returns on if the request came in through a secure channel (with SSL encryption), or off if the request is for an unsecure channel.
HTTPS_KEYSIZE | Specifies the number of bits in the SSL connection key size.
HTTPS_SECRETKEYSIZE | Specifies the number of bits in server certificate private key.
HTTPS_SERVER_ISSUER | Specifies the issuer field of the server certificate.
HTTPS_SERVER_SUBJECT | Specifies the subject field of the server certificate.
INSTANCE_ID | Not supported in ISA, will always return the error (ERROR_INVALID_INDEX).
INSTANCE_META_PATH | Not supported in ISA, will always return the error (ERROR_INVALID_INDEX).
PATH_INFO | Not supported in ISA, will always return the error (ERROR_INVALID_INDEX).
PATH_TRANSLATED | Not supported in ISA, will always return the error (ERROR_INVALID_INDEX).
QUERY_STRING | Not supported in ISA, will always return an empty string.
REMOTE_ADDR | Specifies the IP address of the client or agent of the client (for example gateway, proxy, or firewall) that sent the request.
REMOTE_HOST | Specifies the host name of the client or agent of the client (for example, gateway, proxy or firewall) that sent the request if reverse Domain Name System (DNS) is enabled. Otherwise, this value is set to the IP address specified by REMOTE_ADDR.
REMOTE_USER | Specifies the user name supplied by the client and authenticated by the server. This comes back as an empty string when the user is anonymous.
REQUEST_METHOD | Specifies the HTTP request method verb.
SCRIPT_NAME | Not supported in ISA, will always return "w3proxy.dll".
SERVER_NAME | Specifies the server's host name, or IP address, as it should appear in self-referencing URLs.
SERVER_PORT | Specifies the TCP/IP port on which the request was received.
SERVER_PORT_SECURE | Specifies a string of either 0 or 1. If the request is being handled on the secure port, then this will be 1. Otherwise, it will be 0.
SERVER_PROTOCOL | Specifies the name and version of the information retrieval protocol relating to this request.
SERVER_SOFTWARE | Not supported by ISA, will always return "Microsoft-ISA/1.0.
URL | Not supported in ISA, will return the request URL (after the request has been parsed). HTTP_Proxy_URL will also return this value.

lpvBuffer
Points to the buffer to receive the requested information.
lpdwSizeofBuffer
Points to a DWORD data type that indicates the size of the buffer pointed to by lpvBuffer. On successful completion, the DWORD contains the size of bytes transferred into the buffer, including the null-terminating byte.

Return Values

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. The Win32® GetLastError function can be used to determine why the call failed. The following are the possible error values.

Value | Meaning
ERROR_INVALID_PARAMETER | Bad connection handle, or invalid values, in either lpszVariableName or lpdwSizeofBuffer.
ERROR_INVALID_INDEX | Bad or unsupported variable identifier.
ERROR_INSUFFICIENT_BUFFER | Buffer too small. The required buffer size is *lpdwSizeofBuffer.
ERROR_NO_DATA | The data requested is not available.


ServerSupportFunction

Points to the ServerSupportFunction function used to extend the Web (ISAPI) filter functions. Parameters are specific to the extensions. The ServerSupportFunction callback function can be used by Web (ISAPI) filters to accomplish a wide variety of tasks.

The ServerSupportFunction function is declared as:

BOOL WINAPI * ServerSupportFunction(
  PHTTP_FILTER_CONTEXT pfc,
  enum SF_REQ_TYPE sfReq,
  PVOID pData,
  DWORD ul1,
  DWORD ul2
);

The parameter sfReq specifies the particular support function that is to be executed by the ISA Web proxy service. The remaining parameters are described in the individual support function sections; see the following list:

SF_REQ_ADD_HEADERS_ON_DENIAL

SF_REQ_DISABLE_NOTIFICATIONS

SF_REQ_NORMALIZE_URL

SF_REQ_SEND_RESPONSE_HEADER

SF_REQ_SET_NEXT_READ_SIZE

Note If a parameter is designated as unused for a particular support function, you should set the parameter to NULL or 0, as appropriate.

SF_REQ_GET_CONNID is not supported by ISA or by IIS 4.0 or later, and will return 0.

SF_REQ_GET_PROPERTY is not supported by ISA and will return 0.

SF_REQ_SET_PROXY_INFO is not used in the ISA implementation of ISAPI.


SF_REQ_ADD_HEADERS_ON_DENIAL

This support function allows your Web (ISAPI) filter to add specified headers to the server error response, in the event that the HTTP request is denied by the server. This allows an authentication filter to advertise its services without filtering every request.

Note This support function will not work properly if called during the processing of a SF_NOTIFY_SEND_RAW_DATA notification.

BOOL WINAPI * ServerSupportFunction(
  PHTTP_FILTER_CONTEXT pfc,
  enum SF_REQ_TYPE SF_REQ_ADD_HEADERS_ON_DENIAL,
  PVOID pData,
  DWORD ul1,
  DWORD ul2
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP transaction.
pData
Null-terminated string pointing to one or more HTTP header lines. Each individual header should be terminated with a carriage return and linefeed.
ul1
Unused in this support function.
ul2
Unused in this support function.

Remarks

Generally, the HTTP headers should be WWW-Authenticate headers that specify custom authentication schemes. However, no restriction is placed on which headers can be specified. The ISA Web proxy service will advertise both Basic and integrated Windows authentication, individually and collectively, if those authentication schemes are enabled.


SF_REQ_DISABLE_NOTIFICATIONS

This support function can be used to disable specific notification types for your Web (ISAPI) filter, for the remaining lifetime of that request. If a particular notification event is disabled for your filter, the ISA Web server will not call your filter when that notification event occurs.

New requests will generate the notifications for which your filter registered when it was loaded.

BOOL WINAPI * ServerSupportFunction(
  PHTTP_FILTER_CONTEXT pfc,
  enum SF_REQ_TYPE SF_REQ_DISABLE_NOTIFICATIONS,
  PVOID pData,
  DWORD ul1,
  DWORD ul2
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP transaction.
pData
Unused in this support function.
ul1
Contains flags, described in HTTP_FILTER_VERSION, that indicate which notification types are to be disabled.
ul2
Unused in this support function.


SF_REQ_NORMALIZE_URL

This support function can be used to normalize the URL. Normalization includes decoding hex codes, removing illegal characters, and some internationalization conversions.

BOOL WINAPI * ServerSupportFunction(
  PHTTP_FILTER_CONTEXT pfc,
  enum SF_REQ_TYPE SF_REQ_NORMALIZE_URL,
  PVOID pData,
  DWORD ul1,
  DWORD ul2
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP transaction.
pData
Points to the URL string to normalize.
ul1
Unused in this support function.
ul2
Unused in this support function.


SF_REQ_SEND_RESPONSE_HEADER

You can use this support function to ask the ISA Web proxy service to send a complete HTTP response header to the client browser, including the HTTP status, server version, message time, and MIME version. Your filter can also, optionally, append other header information to the end of a header generated by the ISA Web proxy service, such as a Content-Type or Content-Length header.

BOOL WINAPI * ServerSupportFunction(
  PHTTP_FILTER_CONTEXT pfc,
  enum SF_REQ_TYPE SF_REQ_SEND_RESPONSE_HEADER,
  PVOID pData,
  DWORD ul1,
  DWORD ul2
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current active HTTP transaction.
pData
Points to a null-terminated string that contains an HTTP status string, such as "401 Access Denied." If pData is set to NULL, then the default response, "200 OK," will be sent in the response header.
ul1
Points to a null-terminated string that contains the optional HTTP headers that you want to be appended to the response header.
ul2
Unused in this support function.

Note

If you append your own headers to the server-generated headers, you must terminate the header string with an extra carriage return and linefeed.

This support function can be called only once for each HTTP request.

Remarks

An ISAPI Filter may cause a recursive call of itself or a simple call of another ISAPI Filter inside itself. This may occur if an ISAPI filter sends a response using either the ServerSupportFunction (SF_REQ_SEND_RESPONSE_HEADERS), or WriteClient.

We will consider two cases:

  • The call was from a RAW_DATA notification, either READ_RAW_DATA or SEND_RAW_DATA.
  • The call was from any other notification (non-RAW_DATA).

In both cases all filters subscribe to the SEND_RESPONSE notification, which will be called if the ServerSupportFunction(SF_REQ_SEND_RESPONSE_HEADERS) was used.

If the call was from a RAW_DATA notification then only filters with higher order then the filter that sent the response will be called in the SEND_RAW_DATA notification.

If the call was from any other notification, then the filter that sent the response and the filters with higher order will be called in the SEND_RAW_DATA notification.

For example:

Suppose you have 3 filters: Filter_Low with low priority, Filter_Medium with medium priority, and Filter_High with high priority. Filter_Low and Filter_High subscribed to SEND_RESPONSE and SEND_RAW_DATA. Filter_Medium subscribed to SEND_RESPONSE and SEND_RAW_DATA as well, but has also subscribed to another notification.

From its extra notification, Filter_Medium sends either ServerSupportFunction(SF_REQ_SEND_RESPONSE_HEADER) or WriteClient.

The way ISA will call the filters before the ServerSupportFunction(SF_REQ_SEND_RESPONSE_HEADER) or WriteClient return will be as follows:

  • If ServerSupportFunction(SF_REQ_SEND_RESPONSE_HEADER) or WriteClient is sent from RAW_NOTIFICATION then only Filter_High will be called by the SEND_RAW_DATA notification.
  • If ServerSupportFunction(SF_REQ_SEND_RESPONSE_HEADER) or WriteClient I sent from a non-RAW_DATA notification then both Filter_Medium and Filter_High will be called, but Filter_Low will not be called by the SEND_RAW_DATA notification.
  • If ServerSupportFunction(SF_REQ_SEND_RESPONSE_HEADERS) is sent from anywhere, then all filters that subscribed to SEND_RESPONSE will be called, including Filter_Low.


SF_REQ_SET_NEXT_READ_SIZE

This support function is used by raw-read Web (ISAPI) filters to set the number of bytes that will be read during the next read event.

BOOL WINAPI * ServerSupportFunction(
  PHTTP_FILTER_CONTEXT pfc,
  enum SF_REQ_TYPE SF_REQ_SET_NEXT_READ_SIZE,
  PVOID pData,
  DWORD ul1,
  DWORD ul2
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current active HTTP transaction.
pData
Unused in this support function.
ul1
Specifies the size, in bytes, that will be read during the next read event.
ul2
Unused in this support function.

Remarks

This support function is meaningful only for filters that are responding to raw-read events, and that return the status code SF_STATUS_REQ_READ_NEXT from their entry-point function HttpFilterProc.


WriteClient

Points to the WriteClient function that sends raw data back to the client. The WriteClient callback function is called by a Web (ISAPI) filter to send data to the client.

Note

For more information on the correct usage of WriteClient, see SF_REQ_SEND_RESPONSE_HEADER.

The WriteClient function is declared as:

BOOL WINAPI * WriteClient(
  PHTTP_FILTER_CONTEXT pfc,
  LPVOID buffer,
  LPDWORD lpdwBytes,
  DWORD dwReserved
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP transaction.
buffer
A buffer containing data to send to the client.
lpdwBytes
The size of the buffer pointed to by buffer.
dwReserved
Reserved for future use.


HTTP_FILTER_LOG

The ISA Web proxy service includes a pointer to this structure when it is writing information to a log file. If your filter must be notified for this event, it should register for the SF_NOTIFY_LOG event.

typedef struct _HTTP_FILTER_LOG {
  const CHAR * pszClientHostName;
  const CHAR * pszClientUserName;
  const CHAR * pszServerName;
  const CHAR * pszOperation;
  const CHAR * pszTarget;
  const CHAR * pszParameters;
  DWORD dwHttpStatus;
  DWORD dwWin32Status;
  DWORD dwBytesSent;
  DWORD dwBytesRecvd;
  DWORD msTimeForProcessing;
} HTTP_FILTER_LOG, *PHTTP_FILTER_LOG;

Members

pszClientHostName
The client's host name.
pszClientUserName
The client's user name.
pszServerName
The name of the server to which the client is connected.
pszOperation
The HTTP operation type.
pszTarget
The target of the HTTP command.
pszParameters
The parameters passed to the HTTP command.
dwHttpStatus
The HTTP return status.
dwWin32Status
The Win32® error code.
dwBytesSent
The number of bytes sent from the server to the client.
dwBytesRecvd
The number of bytes received by the server from the client.
msTimeForProcessing
The time in milliseconds required to process the client request.

Remarks

When the server is about to log information to the server log file, this structure is pointed to by the pvNotification parameter in the HttpFilterProc function when the notificationType parameter is SF_NOTIFY_LOG. The strings cannot be changed, but the string pointers can be replaced. If string pointers are changed, the memory they point to must remain valid until the next filter notification. The AllocMem callback function in the HTTP_FILTER_CONTEXT structure can be used to ensure this.


HTTP_FILTER_PREPROC_HEADERS

The ISA Web proxy service includes a pointer to this structure when it is preprocessing a request's headers. If your filter must be notified for this event, it should register for the SF_NOTIFY_PREPROC_HEADERS event.

typedef struct _HTTP_FILTER_PREPROC_HEADERS {
  BOOL (WINAPI * GetHeader);
  BOOL (WINAPI * SetHeader);
  BOOL (WINAPI * AddHeader);
  DWORD HttpStatus;
  DWORD dwReserved;
} HTTP_FILTER_PREPROC_HEADERS, *PHTTP_FILTER_PREPROC_HEADERS;

Members

GetHeader
Points to the GetHeader function, which retrieves the specified header value. Header names should include the trailing colon (:). The special values method, URL, and version can be used to retrieve the individual portions of the request line. The special values are case sensitive and must not include the trailing colon.
SetHeader
Points to the SetHeader function, which changes or deletes the value of a header. The function can be used to change the special values included in the request line.
AddHeader
Points to the AddHeader function to add a header to the response.
HttpStatus
The current HTTP status code.
dwReserved
A DWORD reserved for later use.

Remarks

When the server is about to process the client headers, this structure is pointed to by the pvNotification parameter in the HttpFilterProc when the notificationType parameter is set to SF_NOTIFY_PREPROC_HEADERS.


HTTP_FILTER_RAW_DATA

The ISA Web proxy service includes a pointer to this structure when it is either reading or sending raw data. If your filter must be notified for this event, it should register for either the SF_NOTIFY_READ_RAW_DATA or SF_NOTIFY_SEND_RAW_DATA events.

typedef struct _HTTP_FILTER_RAW_DATA {
  PVOID pvInData;
  DWORD cbInData;
  DWORD cbInBuffer;
  DWORD dwReserved;
} HTTP_FILTER_RAW_DATA, *PHTTP_FILTER_RAW_DATA;

Members

pvInData
Points to the data buffer.
cbInData
The amount of data in the buffer pointed to by pvInData.
cbInBuffer
The size of the buffer pointed to by pvInData.
dwReserved
Reserved for future use.

Remarks

This structure is passed to the SF_NOTIFY_READ_RAW_DATA and SF_NOTIFY_SEND_RAW_DATA notification routines. The pvInData pointer can be replaced by filters that modify the raw data being sent or received. (cbInData and cbInBuffer must also be appropriately updated if the pointer is replaced.) The new buffer memory must remain valid until the end of the request. The new buffer memory can remain valid by using AllocMem or by using a buffer owned by the filter. In addition, the filter must not attempt to free or otherwise de-allocate the old pvInData pointer. Only the owner of the memory block is allowed to free the buffer.

Warning It is not recommended that filters modify the raw data in place. The memory segment may be read-only or the data may be cached directly by an ISAPI extension.

Filters that register for the SF_NOTIFY_READ_RAW_DATA event must be assigned at the Web proxy service level. They cannot be assigned to an individual Web site.


HTTP_FILTER_SEND_RESPONSE

Web (ISAPI) filters receive this notification immediately before they send headers to the client. The filter can inspect, modify, or add headers that the client will receive as part of the response to the client's original request. The structure contains the same members as HTTP_FILTER_PREPROC_HEADERS. When a filter has registered for the SF_NOTIFY_SEND_RESPONSE event, the pvNotification parameter of HttpFilterProc will point to this structure.

Note SF_NOTIFY_SEND_RESPONSE is not used when the ISA Web proxy service sends a response. However, it is called when a filter generates a response itself using ServerSupportFunction (SF_REQ_SEND_RESPONSE_HEADER).

typedef struct HTTP_FILTER_SEND_RESPONSE {
  BOOL (WINAPI * GetHeader);
  BOOL (WINAPI * SetHeader);
  BOOL (WINAPI * AddHeader);
  DWORD HttpStatus;
  DWORD dwReserved;
} HTTP_FILTER_SEND_RESPONSE, *PHTTP_FILTER_SEND_RESPONSE;

Members

GetHeader
Points to the GetHeader function, which retrieves the specified header value. Header names must include the trailing colon (:).
SetHeader
Points to the SetHeader function, which changes or deletes the value of a header. The function can be used to change the special values included in the request line.
AddHeader
Points to the AddHeader function to add a header to the response.
HttpStatus
The current HTTP status code.
dwReserved
A DWORD data type reserved for later use.


HTTP_FILTER_URL_MAP

This structure does not apply to ISA's implementation of ISAPI.


HTTP_FILTER_VERSION

This structure is used by GetFilterVersion to obtain the version information about the filter.

typedef struct _HTTP_FILTER_VERSION {
  DWORD dwServerFilterVersion;
  DWORD dwFilterVersion;
  CHAR lpszFilterDesc[SF_MAX_FILTER_DESC_LEN];
  DWORD dwFlags;
} HTTP_FILTER_VERSION, *PHTTP_FILTER_VERSION;

Members

dwServerFilterVersion
The ISAPI version in use by the server.
dwFilterVersion
The version number of ISAPI used by the Web (ISAPI) filter. The version used by your filter can be set by using the HTTP_FILTER_REVISION definition from the httpfilt.h header file in the Windows 2000 SDK.
lpszFilterDesc
Points to a null-terminated string that provides a short description of the Web (ISAPI) filter.
dwFlags
Contains flags that indicate for which notification-event types the filter should be notified, and what the filter's priority is. See Event Notifications for a list of priority flag values.


Event Notifications

The following is a table of notifications for which a Web (ISAPI) filter can be registered. The notifications are shown in the order in which they most commonly occur.

Notification Constant | Meaning
SF_NOTIFY_READ_RAW_DATA | Occurs when data is being read from the client. May occur more than once per request.
SF_NOTIFY_PREPROC_HEADERS | Occurs immediately after IIS or ISA has pre-processed headers, but before the program begins to process header content.
SF_NOTIFY_URL_MAP | Occurs after IIS has translated a URL to a physical path on the server. This notification is irrelevant for the ISA Web proxy service, since it does not have any physical URLs. However, it is provided as it was in Microsoft Proxy Server 2.0, for compatibility with earlier versions.
SF_NOTIFY_AUTHENTICATION | Occurs just before IIS or ISA authenticates the client.
SF_NOTIFY_AUTH_COMPLETE | In HTTP authentication scenario, this notification occurs just after IIS or ISA has determined that access is allowed for the request resource. In a non-authentication scenario, this notification does not occur.
SF_NOTIFY_ACCESS_DENIED | Occurs just after IIS or ISA has determined that access is denied for the request resource, but before IIS or ISA has sent a response to the client.
SF_NOTIFY_SEND_RESPONSE | Occurs after the request has been processed by IIS, but before any headers are sent back to the client. This notification is not used when the ISA Web proxy service sends a response. However, it is called when a filter generates a response itself using ServerSupportFunction (SF_REQ_SEND_RESPONSE_HEADERS).
SF_NOTIFY_SEND_RAW_DATA | Occurs as IIS or ISA sends raw data back to the client. May occur more than once per request.
SF_NOTIFY_END_OF_REQUEST | Occurs at the end of a request.
SF_NOTIFY_LOG | Occurs at the end of a request, just before ISA writes the transaction to the ISA log.
SF_NOTIFY_END_OF_NET_SESSION | Occurs when a network session with a client is ending.

In addition to the notification events, ISAPI makes use of flags relating to filter priority and port security settings.

Filter Priority Settings

Value | Meaning
SF_NOTIFY_ORDER_DEFAULT | Default priority (medium priority).
SF_NOTIFY_ORDER_LOW | Low priority.
SF_NOTIFY_ORDER_MEDIUM | Medium priority
SF_NOTIFY_ORDER_HIGH | High priority

Port Security Settings

Value | Meaning
SF_NOTIFY_SECURE_PORT | Notify the application only for connections over a secure port.
SF_NOTIFY_NONSECURE_PORT | Notify the application only for connections over a nonsecure port.


Error Codes

This section contains error codes that may be returned by ISA. The error codes are organized in three topics:

  • Run-Time Error Codes
  • Alert Server Error Codes


Run-Time Error Codes

The following are the run-time error codes, defined in wspfwerr.h

Message ID | Code | Text | Explanation
FWX_E_TERMINATING | 0xC0040001L | The object is shutting down. |
FWX_E_INVALID_ARG | 0xC0040002L | The argument is invalid. |
FWX_E_ALREADY_IN_BLOCKING_OP | 0xC0040003L | FWX_E_ALREADY_IN_BLOCKING_OP | The blocking operation is already started.
FWX_E_NOT_IN_BLOCKING_OP | 0xC0040004L | FWX_E_NOT_IN_BLOCKING_OP | There is no blocking operation to be ended.
FWX_E_FILTER_NOT_REGISTERE | 0xC0040005L | FWX_E_FILTER_NOT_REGISTERED |
FWX_E_ALREADY_EXISTS | 0xC0040006L | FWX_E_ALREADY_EXISTS |
FWX_E_BUFFERFULL | 0xC0040007L | FWX_E_BUFFERFULL | Not all the data was appended to the buffer object because the buffer was full.
FWX_E_PROTOCOL_RULES_DENIED | 0xC0040008L | FWX_E_PROTOCOL_RULES_DENIED | The protocol rules do not allow the user to use the specified protocol.
FWX_E_ALREADY_EMULATED | 0xC0040009L | FWX_E_ALREADY_EMULATED | The connection is already emulated by another filter.
FWX_E_BAD_CONTEXT | 0xC004000AL | FWX_E_BAD_CONTEXT | The method was not called while handling any of the supported events.
FWX_E_NOT_SUPPORTED | 0xC004000BL | FWX_E_NOT_SUPPORTED | Modifying this property is not allowed for this session.
FWX_E_NOT_AUTHENTICATED | 0xC004000CL | FWX_E_NOT_AUTHENTICATED | Cannot perform the action because the session is not authenticated.
FWX_E_SITE_AND_CONTENT_RULES_DENIED | 0xC004000DL | FWX_E_SITE_AND_CONTENT_RULES_DENIED |


Alert Server Error Codes

The following are the alert server error codes, defined in CometErrorCodes.h.

Message ID | Code | Explanation
S_ALERTSRV_ALERT_NOT_FOUND\ | MAKE_HRESULT(SEVERITY_SUCCESS, FACILITY_ITF, 0x278) | No matching alert was found, thus the SignalEvent actually has no effect. This can happen if the user deliberately deleted an alert that was signaled later. This is a warning, rather than an error.
E_ALERTSRV_UNKNOWN_EVENT | COMET_ERR(0x279) | The event globally unique identifier (GUID) that was used in SignalEvent cannot be found in the storage. This can happen if: 1. The user deleted an ISA event that was signaled later. The user can only do this by tampering with the storage directly, becausee the COM will block this operation. 2. A third-party plug-in is signaling its own event, but that event wasn't installed properly.
E_ALERTSRV_BAD_EVENT_GUID | COMET_ERR(0x280) | The event GUID parameter is invalid because it is not in a GUID format.


Globally Unique Identifiers

ISA supports these MMC-like extensions. The following table lists the ISA snap-in nodes, their globally unique identifiers (GUIDs) and the FPCSnapinNode properties of each node.

Node | GUID | FPCSnapinNode Property ParentArray | FPCSnapinNode Property ParentPolicy | FPCSnapinNode Property CurrentObject 1
FPC | 6E21FA00-0C06-11D2-9A4F-0060081E9D26 | N/A | N/A | IFPC
Arrays | 273843AD-B1B9-4145-BDEF-8F2EB9E52382 | N/A | N/A | IFPCArrays
Array | 545beab0-0c13-11d2-9a4f-0060081e9d26 | This array | N/A | IFPCArray
Policy | 24E13C70-1BDE-11d2-AC22-0060973C0C94 | The containing array, or NULL for enterprise policy. | NULL for array policy, or the enterprise policy. |
Site and Content Rules | 0161C461-1BDE-11d2-AC22-0060973C0C94 | The containing array, or NULL for enterprise policy. | The containing enterprise policy, or NULL for an array local rules. | ISiteandContentRules
Site and Content Rule | 1904c70c-5ea0-11d2-9a14-006094eb634c | The containing array, or NULL for enterprise policy. | The containing enterprise policy, or NULL for an array local rule. | ISiteandContentRule
Protocol Rules | CDD3D751-1C81-11d2-AC22-0060973C0C94 | The containing array, or NULL for enterprise policy. | The containing enterprise policy, or NULL for an array local rules. | IFPCProtocolRules
Protocol Rule | 060fde66-3042-11d2-9a06-006094eb634c | The containing array, or NULL for enterprise policy. | The containing enterprise policy, or NULL for an array local rule. | IFPCProtocolRule
Web Publishing Rules | 29775731-16F5-11d2-AC22-0060973C0C94 | The containing array | N/A | IFPCWebPublishingRules
Web Publishing Rule | e224bd7c-a491-11d2-9a1c-006094eb634c | The containing array | N/A | IFPCWebPublishingRule
IP Packet Filters | 16985841-171E-11d2-AC22-0060973C0C94 | The containing array | N/A | IFPCIpPacketFilters
IP Packet Filters | 30984c30-fbce-11d2-aa2b-00a0c9d05606 | The containing array | N/A | IFPCIpPacketFilter
Policy Elements | BC17E262-1992-11d3-864F-0090272F9EEB | The containing array, or NULL for the enterprise schema. | N/A | IFPCPolicyElements
Schedules | 569b5e0e-d9f3-11d2-9a1e-006094eb634c | The containing array | N/A | IFPCSchedule
Schedule | 173f40a0-d9f2-11d2-9a1e-006094eb634c | The containing array | N/A | IFPCSchedule
Bandwidth Priorities | 582242B7-5BCB-4e17-9D09-A7E394A9C426 | The containing array | N/A | IFPCBandwidthPriorities
Bandwidth Priority | 03869EDB-8558-46d1-BF8E-CF08FF80D9B6 | The containing array | N/A | IFPCBandwidthPriority
Destination Sets | 1f3bb926-6cda-11d2-9a15-006094eb634c | The containing array | N/A | IFPCDestinationSets
Destination Set | 6145fc14-6cda-11d2-9a15-006094eb634c | The containing array | N/A | IFPCDestinationSet
Client Address Sets | f5813a0c-f0d7-11d2-9a24-006094eb634c | The containing array | N/A | IFPCClientAddressSets
Client Address Set | ccf9400c-f0d7-11d2-9a24-006094eb634c | The containing array | N/A | IFPCClientAddressSet
Protocol Definitions | 75032bd0-20a4-11d2-9a54-0060081e9d26 | The containing array | N/A | Not implemented
Protocol Definition | cc0b8e42-29f9-11d3-8a5b-006094eb634c | The containing array | N/A | IFPCProtocolDefinition or IFPCFilterProtocol; depends on object type.
Content Groups | 0223e789-aa75-42aa-a959-7773e41ac062 | The containing array | N/A | IContentGroups
Content Group | a8c24098-72c2-4c1d-aaec-10e889723353 | The containing array | N/A | IContentGroups
Servers | 5301D860-1AE6-11d2-AC22-0060973C0C94 | The containing array | N/A | IFPCServers
Server | 2EA65550-1AE6-11d2-AC22-0060973C0C94 | The containing array | N/A | IFPCServer
Logging | c6a42b60-0de3-11d3-aa33-00a0c9d05606 | The containing array | N/A | IFPCLogs
Log | f03e4a60-0df6-11d3-aa33-00a0c9d05606 | The containing array | N/A | IFPCLog
Alerts | 16985850-171E-11d2-AC22-0060973C0C94 | The containing array | N/A | IFPCAlerts
Alert | fe6eb072-1777-11d3-95a0-0004ac3db3cc | The containing array | N/A | IFPCAlert
Web (ISAPI) Filters | 4A0B8651-A3C5-4064-A783-2E06AA23721F | The containing array | N/A | IFPCWebFilters
Web (ISAPI) Filter | 6A4EC987-E775-41dc-A9D2-27226853D391 | The containing array | N/A | IFPCWebFilter
Cache | 6f9f8dc0-1cc4-11d3-aa34-00a0c9d05606 | The containing array | N/A | IFPCCache
Cache Drive | e89d86e0-1cc3-11d3-aa34-00a0c9d05606 | The containing array | N/A | IFPCCacheDrive
Client Configuration | 18612e10-23e1-11d3-aa35-00a0c9d05606 | The containing array | N/A | IFPCProxyClientConfig
Web Proxy Client (Browser) and Firewall Client | 84058b10-23f1-11d3-aa35-00a0c9d05606 | The containing array | N/A | IFPCBrowserClientConfig for Firewall client, and IFPCFirewallClientConfig for Firewall client.
Application Filters | 7452e8e4-29f9-11d3-8a5b-006094eb634c | The containing array | N/A | IFPCApplicationFilters
Application Filter | 02a589b8-29f9-11d3-8a5b-006094eb634c | The containing array | N/A | IFPCApplicationFilter
Network Configuration | fdbc5130-01f8-11d3-aa2f-00a0c9d05606 | The containing array | N/A | IFPCNetworkConfiguration
Local Domain Table (LDT) | a2095b50-01f3-11d3-aa2f-00a0c9d05606 | The containing array | N/A | IFPCLDT
Local Domain Entry | 138a1240-020e-11d3-aa2f-00a0c9d05606 | The containing array | N/A | IFPCLDTEntry
Local Address Table (LAT) | e52bbe10-06a2-11d3-aa31-00a0c9d05606 | The containing array | N/A | IFPCLAT
Local Address Entry | eae15160-06e2-11d3-aa31-00a0c9d05606 | The containing array | N/A | IFPCLATEntry
Routing | D72690B0-1C80-11d2-AC22-0060973C0C94 | The containing array | N/A | IFPCRoutingRules
Routing Rule | d3f2b790-31f9-11d2-a9ea-00a0c9d05606 | The containing array | N/A | IFPCRoutingRule
Enterprise Policy | 1e5743b0-45ac-41bf-be43-1e6cb6d99503 | N/A | N/A | IFPCEnterprisePolicy
Enterprise Policies | 8d167b45-0a35-400c-b680-f44ddf0ca7f8 | N/A | N/A | IFPCEnterprisePolicies
Monitoring | F1BAF761-823D-4c68-A7C3-463CC696BDD9 |  |  |
Signaled Alerts | 1F199288-7C9E-46e9-9800-840248005605 |  |  | IFPCSignaledAlerts
Signaled Alert | 641893D7-0DC5-4ca6-8A7B-AE784AB0B915 |  |  | IFPCSignaledAlert
Services | A4FC6565-992C-488d-9D6E-9C6F48D96755 |  |  |
Service | 0689FFEB-5F95-4090-A7C6-032542D5A6C1 |  |  |
Sessions | 60DEA196-CEC1-4fec-B4CC-0DD6594C0D21 |  |  |
Session | 41BF2420-6EBE-481f-8F9C-8D333E56A758 |  |  |
Publishing | 4a5530fc-5fc6-4d81-a5a7-e192bdd45dc8 |  |  | IFPCPublishing
Server Publishing Rules | bc96f5d8-a2f9-444f-bf25-341e601b10c3 |  |  | IFPCWebPublishingRules
Server Publishing Rule | 47757a2e-960f-471a-9f43-4b66a128904d |  |  | IFPCWebPublishingRule
Cache Configuration | 6BB2AF2E-91B1-4090-8C89-81DD01F2F71F |  |  | IFPCCacheConfiguration
Scheduled content downloads | FBA1E736-7614-4c49-A8A0-8C9B7A117465 |  |  | IFPCScheduledContentDownload
Scheduled content download | CA0F5779-1016-4d33-B249-29E1A378E4D3 |  |  | FPCScheduledContentDownloadConfig
Monitoring Configuration | 173D69BE-C58F-4a4a-9498-8BB59FD350BD |  |  |
Extensions | 2FA40928-5067-4031-AD13-5F8AA3021447 |  |  |
1 To be defined


Glossary

This glossary defines some of the terms found in the documentation for Internet Security and Acceleration (ISA) Server 2000. Click a letter at the top of the screen to jump to that section of the glossary, or use your browser's Find command to search for a word across the entire glossary.

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


A

access control entry (ACE)
An entry in an access control list (ACL). The entry contains a security identifier (SID) and a set of access rights. A process with a matching SID is either allowed or denied access rights.
access control list (ACL)
A level of Windows® 2000 permission that can be set on a file or a directory allowing specified users access within an NTFS file system directory. An access control entry (ACE) is an entry in the list.
active caching
A mechanism used to automatically initiate new requests to update cached file objects without user intervention. Requests can be activated based on the length of time an object has been cached or was last retrieved from the object's source location. This type of caching can be used to assure the freshness of specified data within the cache. See also passive caching, fresh data.
address spoofing
See DNS spoofing.
alerting
This feature alerts administrators about suspicious network events, such as rejected packets, protocol violations, and a full hard disk. Alerting is enabled when IP packet filtering is turned on and is recorded in the IP packet filtering logs. Event messages can also be sent to a user account by using an SMTP e-mail message.
anonymous logon
This feature allows a user remote access to a computer on the Internet without supplying a user name or password, but provides only the guest permissions assigned to that account. Commonly used in FTP requests. See also IUSR_computername.
application filter
A firewall extension that registers for and processes events related to connection with another network. Application filters are typically designed to enhance the security provided by a firewall by excluding or modifying data that approaches the network.
application gateway
Computer software intended to maintain security on a secluded network yet allow certain traffic to go between the private network and the outside world. See also firewall.
array
A group of ISA server computers used to provide distributed caching, load balancing, and fault tolerance. Arrays allow client requests to be distributed among several ISA server computers, which increases response time for clients. Arrays allow a group of ISA server computers to be treated and managed as a single, logical entity. Array communications are peer-to-peer, not hierarchical, one-way communication between upstream and downstream proxy server computers.
array member
An ISA server computer that is part of an array.
array membership table
A list of ISA computers within an array. Each ISA computer manages its own table.
authentication
Validation of a user's logon information to determine permission to access a resource or perform an operation. See also anonymous logon, Basic authentication, and Windows 2000 challenge/response authentication.
autodial
A component of ISA that enables users to automatically connect to remote networks, such as the Internet, during predetermined times.


B

backup domain controller (BDC)
A server that receives a copy of the security policy and master database for a Windows 2000 domain. The master database contains centralized security data for all domain-assigned users and is updated when changes in security are made. See also primary domain controller (PDC), member server.
bandwidth control
The practice of setting the maximum network capacity that a service is allowed to use. You can deliberately limit a server's workload by not allowing it to receive requests at full capacity, saving resources for other programs such as e-mail.
Basic authentication
A method of authentication that encodes the user name and password. Basic authentication is called "clear text" because the encoding (base-64) can be decoded by anyone with a freely available decoding utility. Note that encoding is not the same as encryption. See also Windows 2000 challenge/response authentication.
BDC
See backup domain controller (BDC).
BIND service
See Domain Name System (DNS).
binding
A process that establishes the initial communication channel between the protocol driver and the network adapter driver.
bits-per-second (bps)
The basic rate of data transmission.
BOOTP
See Bootstrap protocol (BOOTP).
Bootstrap protocol (BOOTP)
A Transmission Control Protocol/Internet Protocol (TCP/IP) protocol that allows a diskless client computer to determine its own Internet Protocol (IP) address, the IP address of the server, and the name of a file to be loaded into memory and executed. DHCP provides a superset of the functions provided by BOOTP.
BPS
See bits-per-second (bps).
broadcasting
The delivery of data packets to all computers on a network.
browser
A tool for navigating and accessing information on either the Internet or an intranet.


C

cache
A store of frequently retrieved objects and URLs located on the cache drive of an ISA computer. Instead of retrieving an object directly from an Internet Web server, the object is stored and retrieved from the cache instead. Caches improve network performance by reducing the number of objects retrieved from the Internet based on their popularity.
cache drive
The amount of space reserved on a selected server disk drive for use in storing cached files.
cache filtering
The ability to either cache or not cache objects retrieved from World Wide Web (WWW), FTP, or Gopher sites.
cache routing
The forwarding of a client HTTP request from one ISA computer to another ISA computer. Also known as cascading or chaining. See hierarchical caching.
CERN-Proxy Protocol
An industry standard for application-aware proxy services over HTTP-based client/server communications. The CERN standards are established by the European Laboratory for Particle Physics (CERN), located in Switzerland.
CGI
See Common Gateway Interface (CGI).
chaining
A method to link multiple ISA computers together. Individual ISA computers and arrays or any combination can be chained. Communication is in an upstream, hierarchical order.
challenge/response
See Windows 2000 challenge/response authentication.
clear text
See Basic authentication.
commit rate
The speed with which objects or URLs are added to the cache.
Common Gateway Interface (CGI)
A standard interface for HTTP server applications. Used by an application that runs on a server to generate dynamic content based on parameters sent by the requesting Web browser.
completion port
A Windows object that efficiently manages threads used for asynchronous I/O.
connected service
A service that provides a managed connection allowing networked computers to communicate reliably. (Also known as streamed service.) TCP and SPX protocols support this type of service. Four important characteristics include:
  • The path for data packets is established in advance.
  • The resources required for a connection are reserved in advance.
  • A connection's resources are reserved throughout the life of that connection.
  • When a connection's data transfer is completed, the connection is terminated and the allocated resources are freed.
connectionless service
A service that emphasizes broadcasting and unacknowledged delivery of data packets. Supports higher throughput speeds for real-time applications. UDP is a protocol that supports this type of service.
credentials
An authentication method used to validate client-to-server and server-to-server communication. Credentials include a user name and a password that is used to validate requests from client computers or from other computers in an array or chain.


D

data filter
An application filter that monitors content, as in a check for viruses, and that can also modify content
Data Source Name (DSN)
The logical name that allows a connection to an ODBC data source, such as a SQL Server database.
demand-dial connectivity
A process used by Autodial to perform on-demand dialout connections either to an Internet service provider or to a corporate office from a branch office.
DHCP
See Dynamic Host Configuration Protocol (DHCP).
DHCP relay agent
The component that relays DHCP and BOOTP broadcast messages between a DHCP server and a client across an IP router.
dial-up networking
A component of Windows 2000 and Windows 95/98 that enables users to connect to remote networks, such as the Internet or an internal network, over a telephone line.
distributed caching
The caching of Internet objects in an array or chain of ISA computers, providing load balancing and fault tolerance. Client requests are sent through the array, to upstream ISA computers, or any combination thereof.

DNS

See Domain Name System (DNS).

DNS spoofing
The practice of assuming the DNS name of another system either by corrupting a name-service cache or by compromising a domain-name server for a valid domain.
domain filtering
Controlling access to specific Internet sites by denying or granting permission based on the Internet computer's domain name or friendly name.
domain name
The computer name that substitutes for a network IP address. For example, www.microsoft.com instead of the IP address 157.45.60.81. Also called the friendly name. See also Domain Name System (DNS).
Domain Name System (DNS)
A protocol and computer-naming hierarchy used throughout the Internet to map computer IP addresses to their domain names. DNS is sometimes referred to as the BIND service.
downstream/upstream routing
The routing of a response from one ISA computer to another ISA computer. Client computers connecting to an ISA computer are always downstream. A request from a client computer always flows upstream to ISA computers until the requested item is found, whether it is in the cache of an ISA computer or from the Internet. ISA sends the response downstream to the client computer.
driver
A software component that allows a computer to send and receive information to and from a hardware device.
DSN
See Data Source Name (DSN).
dual-homed
Having connections to two separate physical networks. Each ISA computer in an array has both an internal and external network adapter for Internet connectivity. The internal adapter connects to the internal network. The external adapter connects to the Internet.
dynamic addressing
The automatic assignment of IP addresses in a changing network.
dynamic filters
Dynamic filters are automatically started by the Firewall service, Web proxy, or SOCKS proxy service. This feature allows the ISA services to automatically open and close communication ports on the external interface when transmission of packets is needed.
Dynamic Host Configuration Protocol (DHCP)
A protocol that offers dynamic assignment of IP addresses and related information for temporarily connected network users. DHCP provides safe, reliable, and simple TCP/IP network configuration, prevents address conflicts, and helps conserve the use of IP addresses through centralized management of address allocation.


E

encryption
The process of making information indecipherable to protect it from unauthorized viewing or use, especially during network transmission or when it is stored on a transportable magnetic medium.
extension mode snap-in
A snap-in that provides functionality only when invoked by a parent snap-in. Extension snap-ins can add nodes to the namespace, or just extend existing nodes with new menus, toolbars, property pages, wizards, or Help.


F

FAT
See file allocation table (FAT).
file allocation table (FAT)
A table or list maintained by some operating systems to keep track of the status of various segments of disk space used for file storage. See also Windows 2000 file system (NTFS).
file transfer protocol (FTP)
The Internet standard protocol for transferring files between computers. FTP uses the Telnet and TCP protocols. The server requires a client to supply a logon user name and password before honoring requests. See also anonymous logon.
filter
A means of excluding information that does not match a predefined set of specifications. See application filter.
firewall
A security system intended to protect an organization's network against external threats, such as hackers, coming from another network, such as the Internet. See also application gateway.
Firewall service
An API service used by ISA that provides redirection and remote execution of Windows Sockets (Winsock) applications over connections involving a computer on an internal network (intranet) computer and remote computers on the Internet.
firewall service completion port
A completion port created by Windows 2000 at the request of the Firewall service that is associated with the proxy. See completion port.
FQDN
See fully qualified domain name.
fresh data
Cached data that is verified to be current and consistent with its source.
FTP
See File Transfer Protocol (FTP).
fully qualified domain name (FQDN)
In TCP/IP, host names with their domain names appended to them. For example, a computer with host name zebra and domain name microsoft.com has an FQDN of zebra.microsoft.com. See also Domain Name System (DNS).


G

gateway
A device that routes data packets between multiple TCP/IP networks having dissimilar transport protocols. ISA can act as a gateway between an internal network (an intranet) and the public network (the Internet). See also router.
Gopher
A hierarchical system for finding and retrieving information from the Internet or an intranet. An enhanced version, Gopher Plus, returns more information about an item, such as file size, last date of modification, and the administrator's name. A display of all files available on a Gopher server is called the Gopherspace.
group
In a Windows 2000 Server network, an account containing user accounts that are called members. The permissions and rights granted to a group are also provided to its members, making groups a convenient way to grant common capabilities to collections of user accounts. Groups are assigned unique names within a domain.


H

hash
A mathematical algorithm used for routing client requests within an array or a chain. The result of the hash determines which specific ISA computer to send the client request.
header
In data packet communications, a specified number of bytes that precedes the actual data being transmitted. It identifies control information used to deliver, route, and process the data contents of a packet.
hierarchical caching
The forwarding of a client HTTP request from one ISA computer to another ISA computer upstream. The downstream (source) ISA computer forwards client requests that it cannot service from its own cache. Hierarchical caching uses upstream routing and is a subset of distributed caching.
hierarchical chaining
Linking multiple ISA computers together to form a chain. Individual ISA computers, arrays, or any combination can be chained.
hit rate
The percentage of client requests fulfilled through previously cached data, in contrast to the total of all client requests that have been processed by the caching service.
home directory
See root directory.
host name
The name given to a computer that is part of a Windows 2000 network domain and used for client authentication. Also called the computer name. See also fully qualified domain name (FQDN).
HOSTS file
See LMHOSTS file.
HTTP filter
A Hypertext Transfer Protocol (HTTP) filter provided with ISA, that forwards HTTP requests from Firewall and secure network address translation (SecureNAT) clients to the Web Proxy service.


I

ICMP
See Internet Control Message Protocol.
IIS
See Internet Information Services.
IMC
See Internet Mail Connector.
inbound access
Ability to send information from an external network, such as the Internet, to an internal or external network. See also outbound access.
Integrated Services Digital Network (ISDN)
A dial-up connection to the Internet installed by your Internet service provider (ISP) or telephone company. An ISDN line can offer speeds up to 128,000 bits-per-second (bps) and must be installed at both the server site and the remote site.
interactive application
A program written in C, Perl, or as a Windows 2000 batch file. The user initiates the program by clicking a link in a hypertext document.
Internet Control Message Protocol (ICMP)
The Internet standard protocol subset of IP that handles control and error messages. Gateways use ICMP to send problem reports on packets back to the source that sent the packet.
Internet Information Services (IIS)
The Microsoft® Internet server feature designed for implementing and managing Web sites. Although IIS supports multiple protocols, it primarily transmits information in HTML pages by using HTTP. ISA integrates fully with IIS and Windows 2000 Server.
Internet Mail Connector (IMC)
A component of Microsoft Exchange Server that runs as a Windows 2000 Server service. You can use the Internet Mail Connector to exchange information with other systems that use the Simple Mail Transfer Protocol (SMTP).
Internet Protocol (IP)
The Internet standard routing protocol that defines the IP datagram as the unit of data transfer and provides the IP address scheme to route packets from one network location to another. IP includes the ICMP protocol. The Internet protocol suite is often called TCP/IP.
Internet Relay Chat (IRC)
An Internet standard protocol that supports interactive, real-time, text-based communications in established "chat rooms" on the Internet by means of IRC servers.
Internet Server Application Programming Interface (ISAPI)
A Microsoft-developed API for establishing procedural calls between Internet-based applications and the underlying operating system.
Internet Service Manager
The tool used with Internet Information Services (IIS) to administer services.
Internetwork Packet Exchange (IPX)
A routing protocol developed for Novell Netware networks that is used in place of IP to manage data transfer between computers. Windows NT/Windows 2000implements IPX through NWLink.
IP
See Internet Protocol.
IP address
A unique address that identifies a computer on a network by using a 32-bit address that is unique across a TCP/IP network. An IP address is usually represented in dotted-decimal notation, which depicts an octet (8 bits, or 1 byte) of an IP address as its decimal value and separates each octet with a period; for example, 102.54.94.97.
IP forwarding
IP forwarding (IP routing) normally allows packets to be forwarded on the internal network.
IP packet filtering
Filtering that either allows or blocks packets destined to specific services on or behind the ISA computer.
IP packet filtering log
The log where IP packet filter events are recorded. The file is identified with PF as the first two letters in the log file name.
IPX/SPX
See Internetwork Packet Exchange (IPX), Sequenced Packet Exchange (SPX).
IRC
See Internet Relay Chat.
ISAPI
See Internet Server Application Programming Interface.
ISDN
See Integrated Services Digital Network.
ISDN interface card
Similar in function to a modem, an ISDN card is hardware that enables a computer to connect to other computers and networks on an Integrated Services Digital Network (ISDN).
IUSR_computername
A default account with anonymous logon privileges for accessing Internet-based services such as FTP, WWW, and Gopher. This account is created during the installation of Internet Information Services (IIS).


K

keep-alives
A keep-alive message is a type of broadcast message, which both the client and the server must support, that determines whether an idle connection is still active. After a network service completes an initial connection request, it uses keep-alive messages to keep the idle connection available for subsequent requests. As a performance-optimizing feature, keep-alive messages avoid the substantial cost of establishing and terminating connections.


L

LAT
See Local Address Table.
LMHOSTS file
A text-based file that maps IP addresses to the friendly names of Windows 2000 computers. This file is used as a static routing table in Windows 2000 Server to authenticate and register valid nodes in a local TCP/IP network.
Local Address Table (LAT)
A table of all internal IP address pairs on the internal network where ISA is installed. This list is used to control access between clients on the internal network and remote IP addresses on external IP networks (or the Internet). The LAT is registered and stored in a text-based file within the installed directory for ISA. This file is distributed to clients during setup and updated periodically by ISA.


M

management information database (MIB)
A standard database component that uses the Simple Network Management Protocol (SNMP) protocol to communicate information about hardware and software processes on your network for further management and monitoring.
member server
A server that has been assigned to a Windows 2000 domain, but is not designated as either the primary domain controller (PDC) or the backup domain controller (BDC) within the assigned domain.
MIB
See management information database (MIB).
Microsoft Management Console (MMC)
General, ISV-extensible common management console in Windows 2000. The MMC console is a Windows-based multiple document interface (MDI) application. MMC itself provides no management behavior, but instead provides a common environment for the snap-ins, which provide the actual management functionality.
MIME
See Multipurpose Internet Mail Extensions.
MMC
See Microsoft Management Console.
mode of extensibility
Behavior that a snap-in provides, extending the console with more functionality. Microsoft has defined several modes of extensibility, and every snap-in must provide at least one of those modes.
.MSC file
A "Management Saved Console" file that constitutes a tool. Once an administrator has assembled a tool using various snap-ins, the administrator can save the tool in an .MSC file, which can be opened and used again later. An .MSC file can be passed on to another administrator. Any administrator can open the .MSC file in MMC, causing the tool to be loaded.
multihomed
A computer with network connections to multiple separate physical networks.
Multiple Document Interface (MDI)
An interface that supports multiple simultaneous views, or windows. A Single Document Interface (SDI) such as Microsoft Internet Explorer does not support multiple views.
Multipurpose Internet Mail Extensions (MIME)
A way of configuring browsers to view files that are in multiple formats. MIME permits the exchanging of objects, different character sets, and multimedia in e-mail on different computer systems.


N

name resolution
The process of mapping a computer name (friendly name) into its corresponding numeric IP address.
namespace
A tree-formatted, ordered listing of all the nodes available in the current tool. The display of the namespace is similar to a folder and directory structure on a hard drive. Required for the Domain Name System (DNS) to work properly. The DNS namespace is hierarchical in nature and allows host names to be stated in absolute or relative terms. Absolute names, or fully qualified domain names (FQDNs), are defined from the root of the name space and uniquely identify a node in the hierarchy. Relative names are represented relative to a name in the hierarchy.
negative caching
The caching of HTTP error conditions associated with accessing a particular URL. If the URL is unavailable, the error response message can be cached and returned to subsequent clients that request the same URL.
NetBIOS
See network basic input/output system (NetBIOS).
NetBIOS Extended User Interface (NetBEUI)
A network protocol usually used in small, department-sized local area networks (LANs). It can use Token Ring source routing as its only method of routing. See also network basic input/output system (NetBIOS), router.
network address translation (NAT)
The process of converting between IP addresses used within an intranet or other private network and Internet IP addresses. See also SecureNAT.
network basic input/output system (NetBIOS)
An API that can be used by applications on a local area network (LAN). NetBIOS provides applications with a uniform set of commands for mapping input/output (I/O) operations into equivalent network operations.
Network News Transfer Protocol (NNTP)
The Internet standard protocol for posting, distributing, and reading network news messages posted among news groups on the Internet. Messages are posted to NNTP servers and are accessed by NNTP clients (newsreaders).
NNTP
See Network News Transfer Protocol (NNTP).
NTFS File System
An advanced file system used by Windows NT/Windows 2000 that supports file system recovery, very large storage media, and object-oriented applications. NTFS also offers enhanced security over the older FAT file system.
NWLink IPX/SPX Compatible Transport
A standard network protocol that supports routing and allows Novell NetWare client/server applications to communicate with IPX/SPX applications.


O

Open Database Connectivity (ODBC)
ODBC is an API that enables applications to access data from a variety of database systems.
outbound access
Ability to send information from an internal or internal network to an external network, such as the Internet. See also inbound access.


P

package
Snap-ins collected into a unit for shipment by a software vendor.
package definition file (PDF)
A file used by Microsoft Systems Management Server for automatic installation of client software. The PDF can also be used for automatic uninstallation of client software for 32-bit Windows-based clients.
passive caching
In this type of service, data is cached and discarded entirely on the basis of object size, popularity, or time since the requested object was last updated in the cache. Frequently referred to as on-demand caching because all caching updates are user-initiated. See also active caching.
password authentication
See authentication.
PDC
See primary domain controller.
PDF
See package definition file (PDF).
Peer Web Services
A collection of services that enable a computer running Windows NT Workstation/Windows 2000 Professional to publish a personal Web site from the desktop. These services include the WWW service, the FTP service, and the Gopher service.
phonebook entry
Used to dial the access number of an Internet service provider (ISP) by using Remote Access Service (RAS) from the Autodial service.
ping
A TCP/IP utility that verifies connections to one or more remote computers by sending ICMP packets and listening for reply packets.
plug-ins
Third-party applications that are installed to extend and enhance the functionality of ISA.
Point-to-Point Protocol (PPP)
In contrast to SLIP, this more recently established Internet communications protocol standardizes dial-up networking that uses analog modem hardware and standard telephone lines. Although PPP is a well-standardized protocol, vendor implementations of PPP service can vary significantly.
Point-to-Point Tunneling Protocol (PPTP)
A newer networking protocol that enables remote users to access corporate networks securely across the Internet by dialing into an Internet service provider (ISP) or by connecting directly to the Internet. PPTP supports multiprotocol virtual private networks (VPNs). Because PPTP allows multiprotocol encapsulation, users can send any packet type over an IP network.
popularity
A measure of the frequency with which objects or URLs are requested by client applications, such as Web browsers. See also cache.
port number
A number that identifies a certain Internet application with a specific connection. Ports are used in TCP to name the ends of logical connections that carry long-term conversations. See also well-known port number.
Post Office Protocol (POP)
A network protocol that permits a client computer to access e-mail on a server. Usually, this means that a POP3 server is used to allow a client computer to retrieve mail that an SMTP server is holding for it.
primary domain controller (PDC)
A server assigned to authenticate logons and maintain the security policy for a Windows 2000 domain. This server stores the master database of all domain-assigned security data for users and must be updated when changes in security are made. See also backup domain controller (BDC), member server.
protocol
Software that allows computers to communicate over a network. The Internet protocol is TCP/IP.
proxy
A software program that connects a user to a remote destination through an intermediary gateway.
proxy client
A client computer that must use a proxy server to gain access to network services not directly supported for client usage.
proxy server
A computer that acts as a relay between remote servers and clients to intercept requests and process communications on behalf of proxy clients.
publishing
The process that allows computers sitting downstream from an ISA computer to publish to the Internet. Publishing includes reverse hosting and secure Web publishing.


R

RAS
See Routing and Remote Access Service.
remote administration
The practice of administering a computer from another computer connected across the network.
remote procedure call (RPC)
A message-passing facility that allows a distributed application to call services available on various computers in a network. Used during remote administration of computers.
remote socket
An external socket on the firewall that listens to or connects to the Internet. The remote socket represents the client's internal socket.
retrieve rate
The speed with which objects or URLs are taken from the cache.
reverse hosting
The process by which any server sitting behind ISA can publish to the Internet. See also secure Web publishing and publishing.
root directory
The top-level directory of a disk's directory structure.
router
An intermediary device on a communications network that expedites message delivery.
routing
The process of forwarding packets to other routers. Routing is used with arrays to direct client requests for Internet objects. Routing is done in conjunction with arrays, chained ISA computers, or directly to the Internet.
Routing and Remote Access Service (RRAS)
A Microsoft-developed service that allows remote client computers running Microsoft dial-up networking, all Microsoft RAS clients, or any third-party PPP client to dial in to a network server (RAS server). RAS servers can also be configured to allow local client computers to dial out to servers outside an internal network.
Routing Information Protocol (RIP)
A protocol that enables a router to exchange routing information with a neighboring router.
RPC
See remote procedure call.


S

SAP Agent service
The service that allows IPX name resolution on Firewall client computers.
secure Web publishing
The process by which a server behind ISA can publish to the World Wide Web (WWW) without compromising security. See also reverse hosting and publishing.
SecureNAT
SecureNAT is an extension of the Windows 2000 NAT driver. ISA Server's secure network address translation (NAT) feature provides a degree of address transparency for networked clients. NAT substitutes a global IP address, valid on the Internet, for an internal IP address. ISA Server enhances Windows 2000's underlying NAT functionality, by enabling access control for FTP, Windows NetMeeting for H.323, and T-120 protocols. It also enables rerouting HTTP requests, which can then frequently be satisfied by a local cache. This enhancement greatly improves HTTP performance and lowers bandwidth requirements.
Secure Sockets Layer (SSL)
A protocol that supplies secure data communication through data encryption and decryption. SSL enables communications privacy over networks.
Sequenced Packet Exchange (SPX)
A transport-level protocol developed for use in Novell NetWare networks. SPX is used in place of TCP to verify packet delivery, assure proper sequencing of packet data, and provide connected service between devices on a network. See also Internetwork Packet Exchange (IPX).
Serial Line Internet Protocol (SLIP)
An older industry standard communications protocol that standardizes dial-up networking. See also Point-to-Point Protocol (PPP).
Server Message Block (SMB) protocol
The underlying protocol by which Microsoft Windows 2000-based servers communicate critical service information with one another.
Service Advertising Protocol (SAP)
In the Windows environment, SAP is a service that broadcasts shared files, directories, and printers categorized first by domain or workgroup and then by server name.

In the context of routing and IPX, SAP is used by servers to advertise their services and addresses on the network. Clients use SAP to determine what network resources are available.

Simple Mail Transfer Protocol (SMTP)
An Internet standard protocol used for exchanging e-mail between SMTP servers on the Internet.
Simple Network Management Protocol (SNMP)
A standard protocol used for monitoring your network. See also management information database (MIB).
site and content rules
Rules defined by the ISA administrator that establish whether content on specified destinations can be accessed by specific users and determine when the rule is in effect.
SMTP
See Simple Mail Transfer Protocol.
snap-in
Software that makes up the smallest unit of console extension. One snap-in represents one unit of management behavior (for example, the Windows 2000 event log viewer is a functional unit of management and thus a good candidate to become a snap-in). Technically, snap-ins are OLE InProc servers.
SNMP
See Simple Network Management Protocol.
socket
A logical communications channel used by TCP/IP applications. Sockets are data structures created by using a combination of device IP addresses and reserved TCP/UDP port numbers to indicate connection and delivery service information. See also Windows Sockets.
SOCKS
A protocol for traversing firewalls in a secure and controlled manner, made available to the public by the Internet Engineering Task Force (IETF).
SPX
See Sequenced Packet Exchange.
SQL server
A server that uses the structured query language (SQL) to query, update, and manage a relational database.
SSL
See Secure Sockets Layer.
stand-alone mode snap-in
A snap-in that provides functionality even if loaded alone in a console that has no other snap-ins.
static filters
Filters that allow packets from other administrator-selected services from the Internet. A static filter is created during configuration of ISA by using the user interface. If IP packet filtering is enabled, the static filter is always on.
static IP mapping
A method provided on a WINS server to assign a static (unchanging) IP address to a client.
structured query language (SQL)
A database query and programming language widely used for accessing data in, querying, updating, and managing relational database systems. See also SQL server.
subnet mask
A TCP/IP configuration parameter that extracts network and host configuration from an IP address. This 32-bit value enables the recipient of IP packets to distinguish the network ID portion (domain name) of the IP address from the host ID (host name).
Systems Management Server (SMS)
A Windows 2000 Server network server application that remotely manages the computers on a network. SMS detects computers on the network, inventories software and hardware configurations, and installs client applications from a central location.


T

TCP/IP
See Transmission Control Protocol/Internet Protocol.
Time-to-Live (TTL)
A standard field in a TCP/IP header that indicates an age-of-expiration value that is examined by receiving stations. Data with active TTL values is maintained and forwarded on the network; data with expired TTL values is discarded.
Transmission Control Protocol (TCP)
The Internet standard transport protocol that provides the reliable, two-way connected service that allows an application to send a stream of data end-to-end between two computers across a network. The Internet protocol suite is often called TCP/IP.
Transmission Control Protocol/Internet Protocol (TCP/IP)
A family of networking protocols that allows computers with diverse hardware architectures and various operating systems to communicate across interconnected networks and the Internet. TCP/IP includes standards for how computers communicate and conventions for connecting networks and routing traffic. Every computer on the Internet supports TCP/IP.
TTL
See Time-to-Live.
tunneling
See Point-to-Point Tunneling Protocol.


U

UDP
See User Datagram Protocol.
User Datagram Protocol (UDP)
A standard transport protocol in TCP/IP networking that provides connectionless service for unacknowledged delivery of packets. UDP adds port addresses to the service provided by IP.


V

VDOLive
A stand-alone application that provides stream-oriented service for continuous video imaging. VDOLive Player can be configured to work with Internet Explorer.


W

Web proxy service
The service that provides a means for ISA to act as a proxy server.
well-known port number
The standard, default port numbers used by the Internet community for well known (commonly used) services. For example, the well known port number for the Gopher service is 70; for the World Wide Wweb service, it is 80.
Windows 2000 challenge/response authentication
A method of authentication in which a server uses Windows 2000 security to allow access to its resources.
Windows 2000 file system (NTFS)
See NTFS file system.
Windows 2000 Performance Monitor
A tool used by Windows 2000 to track computer activity by using a predefined set of counters.
Windows 2000 Server Event Viewer
A program provided with Windows 2000 that enables users to monitor system, security, and application events by viewing the Windows 2000 Event Log.
Windows 2000 System Event Log
A Windows 2000 service that records events in the system, security, and application service logs. See also Windows 2000 Server Event Viewer.
Windows Internet Name Service (WINS)
A name resolution service that runs on Windows 2000 Server. WINS maps friendly names to IP addresses. A WINS server handles name registrations, queries, and releases. See also Domain Name System (DNS).
Windows Sockets
A Windows implementation of the widely used University of California-Berkeley Sockets API. Windows Sockets (Winsock) is a networking API used to create TCP/IP-based sockets applications. Winsock provides interfaces between applications and the transport protocol and works as a bidirectional connection for incoming and outgoing data. See also socket.
WINS
See Windows Internet Name Service.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.


Requirements

Many topics that introduce the syntax of an API element contain information about the build and run-time requirements for using the element. The format is as follows:

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in winuser.h.
Import Library: Use user32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

The first line indicates the versions of Windows NT on which an element is supported. This information may include required service packs, option packs, or components such as Internet Explorer. If an element is not supported, the line reads "Windows NT/2000: Unsupported."

The second line indicates whether an element is supported on Windows 95 or Windows 98. This information may include required OEM service releases, redistributables, or components such as Internet Explorer. If an element is not supported, the line reads "Windows 95/98: Unsupported."

The third line indicates the versions of Windows CE on which an element is supported. If an element is not supported, the line reads "Windows CE: Unsupported."

The fourth line indicates the file that defines an element. This value can be an .h file, .idl file, or .odl file. If the header file is supplied by the user, the line reads "Header: User-defined."

The fifth line indicates the file used to resolve calls to a function or member. This value can be a .lib file, .dll file, or .tlb file. If the import library is supplied by the user, the line reads "Import Library: User-defined." For element types that do not require an import library, this line is omitted.

The sixth line indicates whether an element exists as both a Unicode (W) version and an ANSI (A) version. If Unicode support is not available, this line is omitted.